@getxflow/cli 0.20.2 → 0.22.0

package/dist/bin.js

@@ -27,7 +27,9 @@ const skills_1 = require("./commands/skills");
 const sources_1 = require("./commands/sources");
 const storage_1 = require("./commands/storage");
 const deploy_1 = require("./commands/deploy");
+const dev_1 = require("./commands/dev");
 const update_1 = require("./commands/update");
+/** A command that wraps another process answers with its exit code. */
 async function run(args) {
     const [first, second] = args.words;
     const rest = { ...args, words: args.words.slice(1) };
@@ -195,6 +197,8 @@ async function run(args) {
         case 'status':
             await (0, sources_1.status)();
             return;
+        case 'dev':
+            return (0, dev_1.dev)();
         case 'pull':
             await (0, sources_1.pull)(rest);
             return;
@@ -281,8 +285,7 @@ async function main() {
     let nudgeCovered = args.words[0] === 'update';
     try {
         (0, flags_1.checkFlags)(args);
-        await run(args);
-        return 0;
+        return (await run(args)) ?? 0;
     }
     catch (e) {
         if (e instanceof api_1.ApiError) {

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';
@@ -56,7 +57,7 @@ async function dbStatus(args) {
         return;
     }
     const { root, config } = (0, config_1.requireProject)();
-    const client = (0, session_1.connect)(config);
+    const client = await (0, session_1.connectProject)(config.projectId, root, config);
     const local = readMigrations(root);
     const history = await (0, api_1.apiJson)(client, `/api/v1/projects/${config.projectId}/db/migrate`);
     const applied = new Map(history.applied.map((row) => [row.name, row]));
@@ -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`, {
@@ -224,7 +237,7 @@ async function dbQuery(args) {
 }
 async function dbMigrate(args) {
     const { root, config } = (0, config_1.requireProject)();
-    const client = (0, session_1.connect)(config);
+    const client = await (0, session_1.connectProject)(config.projectId, root, config);
     const migrations = requireMigrations(root);
     const dryRun = (0, args_1.flagBool)(args, 'dry-run');
     (0, ui_1.step)(dryRun ? `Checking the migrations (${migrations.length} in the directory)` : `Applying the migrations (${migrations.length} in the directory)`);

package/dist/commands/deploy.js

@@ -171,21 +171,24 @@ 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) {
-    const { projectId, client } = await (0, session_1.projectTarget)(args, { probe: true });
+    const { projectId, client } = await (0, session_1.projectTarget)(args);
     (0, ui_1.step)('Publishing the current dev version');
     const result = await (0, api_1.apiJson)(client, `/api/v1/projects/${projectId}/publish`, { method: 'POST', timeoutMs: 120_000 });
     if (result.already_published) {
@@ -203,7 +206,7 @@ async function rollback(args) {
     if (!deployId) {
         throw new errors_1.CliError('A version number is required', 'To see the versions: xflow deployments. For example: xflow rollback 481203');
     }
-    const { projectId, client } = await (0, session_1.projectTarget)(args, { probe: true });
+    const { projectId, client } = await (0, session_1.projectTarget)(args);
     const result = await (0, api_1.apiJson)(client, `/api/v1/projects/${projectId}/rollback`, { method: 'POST', body: { deploy_id: deployId } });
     (0, ui_1.ok)(`The project now serves the pages of build ${result.deploy_id}`);
     (0, ui_1.out)(result.project_url);
@@ -216,7 +219,7 @@ async function rollback(args) {
     (0, ui_1.note)((0, ui_1.dim)('  Visitors see these pages only after xflow publish'));
 }
 async function deployments(args) {
-    const { projectId, client } = await (0, session_1.projectTarget)(args, { probe: true });
+    const { projectId, client } = await (0, session_1.projectTarget)(args);
     const data = await (0, api_1.apiJson)(client, `/api/v1/projects/${projectId}/deployments`);
     if (data.deployments.length === 0) {
         (0, ui_1.note)('No versions yet. To build and release: xflow deploy');

package/dist/commands/dev.js

@@ -0,0 +1,48 @@
+"use strict";
+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
+ * project is decided here, by the rule every other command follows.
+ *
+ * Answers with the exit code of the server.
+ */
+async function dev() {
+    const { root, config } = (0, config_1.requireProject)();
+    const client = await (0, session_1.connectProject)(config.projectId, root, config);
+    const env = {
+        ...process.env,
+        XFLOW_TOKEN: client.token,
+        // The proxy sends the key to this address unchecked, and the environment beats
+        // .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', () => { });
+    const result = (0, spawn_1.run)('npm', ['run', 'dev'], { 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');
+    }
+    // Killed by a signal: the code a shell would report for it.
+    const signal = result.signal ? node_os_1.constants.signals[result.signal] : 0;
+    return result.status ?? 128 + signal;
+}

package/dist/commands/env.js

@@ -104,7 +104,8 @@ async function envList(args) {
 /** Check that every referenced variable is stored. */
 async function envCheck() {
     const { root, config } = (0, config_1.requireProject)();
-    const { names } = await fetchVariables((0, session_1.connect)(config), config.projectId);
+    const client = await (0, session_1.connectProject)(config.projectId, root, config);
+    const { names } = await fetchVariables(client, config.projectId);
     const { needed, provided, opaque } = referencedByFunctions(root);
     if (needed.size === 0 && provided.size === 0 && opaque.size === 0) {
         (0, ui_1.note)('The functions of this project read no environment variables');
@@ -159,7 +160,7 @@ async function envCheck() {
 }
 async function envSet(args) {
     const { root, config } = (0, config_1.requireProject)();
-    const client = (0, session_1.connect)(config);
+    const client = await (0, session_1.connectProject)(config.projectId, root, config);
     const pair = args.words[1];
     if (!pair || !pair.includes('=')) {
         throw new errors_1.CliError('A NAME=value pair is required', 'For example: xflow env set SMTP_PASSWORD=secret');

package/dist/commands/projects.js

@@ -98,7 +98,7 @@ async function init(args) {
     (0, ui_1.out)(`  ${(0, ui_1.bold)('Next:')}`);
     (0, ui_1.out)(`    cd ${(0, node_path_1.basename)(target)}`);
     (0, ui_1.out)('    npm install');
-    (0, ui_1.out)('    npm run dev        # develop');
+    (0, ui_1.out)('    xflow dev          # develop');
     (0, ui_1.out)('    xflow deploy       # send the code, build and release');
 }
 /**
@@ -160,7 +160,7 @@ async function link(args) {
     if (client.organizationId)
         (0, config_1.writeState)(dir, { organizationId: client.organizationId });
     (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'));
+    (0, ui_1.note)((0, ui_1.dim)('  .env now points at this project, run it locally with xflow dev'));
     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)}`));

package/dist/commands/skills.js

@@ -53,7 +53,7 @@ This project is hosted on the XFlow platform and ships through the \`xflow\` CLI
 through a git push. Read \`${exports.SKILL_IN_PROJECT}\` before deploying, publishing,
 rolling back, touching the database or migrations, cloud functions, schedules,
 environment variables, file storage and uploads, connected accounts or production logs.
-Command list: \`xflow help\`.
+Run the app locally with \`xflow dev\`. Command list: \`xflow help\`.
 `;
 /** The skill ships inside the package, next to dist. */
 function skillSource() {

package/dist/flags.js

@@ -82,6 +82,7 @@ exports.KNOWN = {
     'storage rm': ['folder', 'yes', 'project'],
     'storage remove': ['folder', 'yes', 'project'],
     status: [],
+    dev: [],
     pull: ['into', 'force', 'revision'],
     deploy: ['no-push', 'force', 'allow-removals', 'message'],
     publish: ['project'],
@@ -105,6 +106,7 @@ 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',
+    dev: 'it runs the dev server of the code next to it',
     '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',

package/dist/help.js

@@ -40,6 +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 skills                    pick the agents that get the platform instructions
   xflow mcp install               give the agent platform access without a terminal
 
@@ -163,8 +164,8 @@ and ${(0, ui_1.bold)('connections unlink')} removes the link without naming the
 its variables, for the same reason.
 
 The rest cannot answer without the working copy and have nothing to do with an id
-instead: ${(0, ui_1.bold)('deploy')}, ${(0, ui_1.bold)('pull')}, ${(0, ui_1.bold)('status')}, ${(0, ui_1.bold)('db migrate')}, ${(0, ui_1.bold)('env check')},
-${(0, ui_1.bold)('env set')}. They answer about the files next to them, so
+instead: ${(0, ui_1.bold)('deploy')}, ${(0, ui_1.bold)('pull')}, ${(0, ui_1.bold)('status')}, ${(0, ui_1.bold)('dev')}, ${(0, ui_1.bold)('db migrate')},
+${(0, ui_1.bold)('env check')}, ${(0, ui_1.bold)('env set')}. They answer about the files next to them, so
 they keep asking for a folder. ${(0, ui_1.bold)('projects get')} and ${(0, ui_1.bold)('link')} take no flag either:
 they name the project by its id as an argument.
 
@@ -231,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
@@ -240,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.
@@ -532,6 +536,22 @@ Plus a few pointer lines in ${(0, ui_1.bold)('AGENTS.md')}. A skill is picked up
 description matches the task, and "add a customers table" will not trigger it. AGENTS.md
 is always read by the agent, which is why the pointer is appended there, at the end of
 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
+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
+in, the right one is found and the folder is bound to it.
+
+Use it instead of a bare ${(0, ui_1.bold)('npm run dev')}, which gets no key from here: its function
+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. 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

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/session.js

@@ -125,16 +125,15 @@ function isProjectId(value) {
  * the default one or XFLOW_API_URL and nothing else: a config lying around must
  * not be able to redirect a call made by id.
  *
- * `probe` is the difference the folder path already has and keeps: publish,
- * rollback and deployments look for the organization of an unbound folder,
- * everything else takes the key it resolves to. Named by id there is no binding
- * to lean on, so the search always happens.
+ * Either way the key comes from connectProject: an unbound folder gets the
+ * organization of its project looked up once and written down, an id gets it
+ * looked up on every call.
  *
  * `root` is that folder, and null when the id was named: a command that reads the
  * sources for a check of its own then knows the check is not available rather than
  * running it against whatever folder the caller happened to stand in.
  */
-async function projectTarget(args, options) {
+async function projectTarget(args) {
     const named = (0, args_1.flagString)(args, 'project');
     if (named !== undefined) {
         if (!isProjectId(named)) {
@@ -150,6 +149,6 @@ async function projectTarget(args, options) {
         return { projectId: named, client, root: null };
     }
     const { root, config } = (0, config_1.requireProject)();
-    const client = options?.probe === true ? await connectProject(config.projectId, root, config) : connect(config);
+    const client = await connectProject(config.projectId, root, config);
     return { projectId: config.projectId, client, root };
 }

package/dist/spawn.js

@@ -13,7 +13,13 @@ function quote(value) {
     return WINDOWS ? `"${value.replace(/"/g, '""')}"` : value;
 }
 function run(binary, args, options = {}) {
-    const common = { stdio: options.stdio, timeout: options.timeout, encoding: 'utf-8' };
+    const common = {
+        stdio: options.stdio,
+        timeout: options.timeout,
+        cwd: options.cwd,
+        env: options.env,
+        encoding: 'utf-8',
+    };
     return WINDOWS
         ? (0, node_child_process_1.spawnSync)([binary, ...args.map(quote)].join(' '), { ...common, shell: true })
         : (0, node_child_process_1.spawnSync)(binary, args, common);

package/dist/template.js

@@ -1,5 +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");
@@ -16,7 +18,7 @@ An application on XFlow.
 
 \`\`\`bash
 npm install       # dependencies
-npm run dev       # develop on localhost:3000
+xflow dev         # develop on localhost:3000
 xflow deploy      # send the code and build it on the platform
 xflow publish     # show the dev version to visitors
 \`\`\`
@@ -38,14 +40,26 @@ function functionsEnvValue(functions) {
     }
     return JSON.stringify(map);
 }
+/** The platform address the way .env holds it, and the way every template reads it. */
+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', apiUrl.replace(/^https?:\/\//, ''));
-    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/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.20.2';
+exports.CLI_VERSION = '0.22.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.20.2",
+  "version": "0.22.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.20.2, so the copy you are reading can be older than
+These instructions ship with xflow CLI 0.22.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
@@ -270,7 +270,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 +429,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
 
@@ -594,12 +595,12 @@ rejected promises and 5xx responses. The same stream, functions included, is in
 platform UI: open the project, section «Облако» (Cloud), tab «Логи» (Logs). The last 200
 records per project are kept.
 
-Local `npm run dev` does not report anything: these logs exist for what you cannot open
-in your own devtools.
+A local run does not report anything: these logs exist for what you cannot open in your
+own devtools.
 
-Cloud functions do work under `npm run dev`, and nothing has to be configured for that:
-the dev server swaps the access key of the logged-in developer for the same narrow pass and
-forwards the call. If it answers that the key is missing, the fix is `xflow login`.
+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.
 
 ## Environment