@getxflow/cli 0.32.0 → 0.34.0

package/dist/commands/db.js

@@ -66,7 +66,7 @@ function readMigrations(root) {
         .sort()
         .map((file) => ({
         name: file.replace(/\.sql$/i, ''),
-        sql: (0, node_fs_1.readFileSync)((0, node_path_1.join)(dir, file), 'utf-8'),
+        sql: (0, text_file_1.readExactTextFile)((0, node_path_1.join)(dir, file)),
     }));
 }
 function requireMigrations(root) {
@@ -130,7 +130,7 @@ async function dbStatus(args) {
     (0, ui_1.table)(rows);
     if (rows.some((row) => row[1] === 'applied, file changed')) {
         (0, ui_1.out)('');
-        (0, ui_1.warn)('A changed file will not be applied again: write a new migration');
+        (0, ui_1.warn)('A changed file is never applied again and db migrate refuses it: write a new migration');
     }
 }
 function serverRow(server) {

package/dist/commands/deploy.js

@@ -58,7 +58,7 @@ async function waitForBuild(client, projectId, started) {
 async function refreshPlatformEnv(root, client, projectId) {
     const card = await (0, api_1.apiJson)(client, `/api/v1/projects/${projectId}`);
     (0, template_1.writePlatformEnv)(root, card.project_token, client.apiUrl, card.functions, card.function_map);
-    return card.functions.filter((fn) => fn.invoke_url).map((fn) => fn.name);
+    return card.functions.filter((fn) => fn.invoke_url);
 }
 /**
  * Start the build, asking before anything is destroyed.
@@ -191,10 +191,19 @@ async function finishBuild(client, projectId, started, root) {
             (0, ui_1.note)((0, ui_1.dim)('  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)(`  Cloud functions live now: ${functions.map((fn) => fn.name).join(', ')}`));
         if (hasSite)
             (0, ui_1.note)((0, ui_1.dim)('  There is one copy per project, publishing does not hold them back'));
     }
+    // An open function is called by its address and by nothing else: a page holds it
+    // in its own files. Printing it here saves the xflow functions list that every
+    // page needed anyway, and says out loud which functions this build left open.
+    const open = functions?.filter((fn) => fn.is_public) ?? [];
+    if (open.length > 0) {
+        (0, ui_1.note)((0, ui_1.dim)('  Open to anyone, no pass and no key, called at this address:'));
+        for (const fn of open)
+            (0, ui_1.note)((0, ui_1.dim)(`    ${fn.name}  ${fn.invoke_url}`));
+    }
     if (hasSite)
         (0, ui_1.note)((0, ui_1.dim)('  Show the new pages to visitors: xflow publish'));
 }

package/dist/commands/functions.js

@@ -20,20 +20,34 @@ const FUNCTIONS_DIR = 'functions';
 async function functionsList(args) {
     const { projectId, client } = await (0, session_1.projectTarget)(args);
     const data = await (0, api_1.apiJson)(client, `/api/v1/projects/${projectId}/functions`);
-    if (data.functions.length === 0) {
+    if (data.functions.length === 0 && !data.shared?.length) {
         (0, ui_1.note)(`No functions. Put the code in ${FUNCTIONS_DIR}/<name>/index.ts and run xflow deploy`);
         return;
     }
-    (0, ui_1.table)(data.functions.map((fn) => [
-        fn.name,
-        fn.status === 'deployed' ? 'deployed' : fn.status === 'failed' ? 'failed' : fn.status,
-        accessLabel(fn),
-        fn.last_deployed_at ? (0, ui_1.formatAge)(fn.last_deployed_at) : '-',
-        // The address is not a secret (the app bundle carries it): a page or a
-        // webhook needs it, and asking the user to copy it out of the UI was a detour.
-        fn.invoke_url ?? '',
-        fn.error_message ?? '',
-    ]));
+    if (data.functions.length > 0) {
+        (0, ui_1.table)(data.functions.map((fn) => [
+            fn.name,
+            fn.status === 'deployed' ? 'deployed' : fn.status === 'failed' ? 'failed' : fn.status,
+            accessLabel(fn),
+            fn.last_deployed_at ? (0, ui_1.formatAge)(fn.last_deployed_at) : '-',
+            // The address is not a secret (the app bundle carries it): a page or a
+            // webhook needs it, and asking the user to copy it out of the UI was a detour.
+            fn.invoke_url ?? '',
+            fn.error_message ?? '',
+        ]));
+    }
+    // Not rows of the table above: these are not this project's to deploy, rename or
+    // delete, and invoke and logs do not reach them from here either. Under the table
+    // with the id they need, so calling one is the same command plus --project.
+    if (data.shared?.length) {
+        if (data.functions.length > 0)
+            (0, ui_1.note)();
+        (0, ui_1.note)((0, ui_1.dim)('  Also callable from this project by name, code in another project of the organization:'));
+        const width = Math.max(...data.shared.map((fn) => fn.name.length));
+        for (const fn of data.shared) {
+            (0, ui_1.note)((0, ui_1.dim)(`    ${fn.name.padEnd(width)}  --project ${fn.project_id}`));
+        }
+    }
 }
 function prettyBody(text) {
     try {

package/dist/help.js

@@ -10,7 +10,7 @@ const version_1 = require("./version");
  * covers a neighbour answers for it too.
  */
 const ALIASES = {
-    functions: 'invoke',
+    invoke: 'functions',
     publish: 'deploy',
     deployments: 'rollback',
 };
@@ -354,13 +354,14 @@ kept for 7 days: that is a "caught it right away" safety net, not a backup.
 ${(0, ui_1.bold)('DROP DATABASE')} is never allowed, because the database is shared across the
 organization.
 
-Editing an already applied file achieves nothing: the comparison is by name, not by
-content. ${(0, ui_1.bold)('xflow db status')} lists such a file separately, so write a new migration
-instead.
+Editing an already applied file achieves nothing: ${(0, ui_1.bold)('migrate')} refuses a name that is
+already applied with different content, and ${(0, ui_1.bold)('xflow db status')} lists such a file
+separately. Write a new migration instead.
 
 One logical database can be attached to several projects, so the history may hold
 migrations that are not in your repository. That is normal, but it also means your
-migration can break somebody else's application.`,
+migration can break somebody else's application, and that a name already in that history
+is taken for you too: ${(0, ui_1.bold)('0001_init')} of a neighbour leaves yours no room.`,
     logs: `${(0, ui_1.bold)('xflow logs')} and ${(0, ui_1.bold)('xflow functions logs')}: project errors
 
 One stream per project: crashes of the released application in the browser and
@@ -561,11 +562,35 @@ has to be deployed already, since the schedule points at it and not the other wa
 
 A failed run shows up in ${(0, ui_1.bold)('xflow functions logs')}: nobody is watching a scheduled
 function, so the wrapper reports a crash the same way it does on an ordinary call.`,
-    invoke: `${(0, ui_1.bold)('xflow functions invoke')} <name>: call a function
+    functions: `${(0, ui_1.bold)('xflow functions')}: what is deployed, and calling it
 
-Calls it exactly the way the application does: the project token plus a visitor pass
-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.
+  xflow functions list            name, state, who may call it, age, address
+  xflow functions invoke <name>   call one the way the application does
+  xflow functions logs [name]     crashes: stack and console output
+
+There is no deploy command of their own: ${(0, ui_1.bold)('xflow deploy')} ships everything in
+${(0, ui_1.bold)('functions/<name>/index.ts')} and then builds the application.
+
+${(0, ui_1.bold)('list')} answers who may reach each function, and the code decides it:
+
+  in-app only        a visitor of the application, with a pass the platform issues
+  external (N keys)  plus an outside service holding a key a human issued in the interface
+  public             plus anyone at all: the code says ${(0, ui_1.bold)("exports.access = 'public'")}
+
+An open function is how a page on xflowpage.ru gets a backend: it answers without a pass
+and without a key, so the page calls the printed address directly and bakes no key into
+its files. Remove the line and deploy again to close it. The function that stays inside
+the application declares nothing, and ${(0, ui_1.bold)("exports.minRole = 'developer'")} raises the
+role the visitor needs. The address is printed for every deployed function; it is not a
+secret, the application bundle carries it.
+
+Under the table, when there are any: the standalone functions of the organization this
+project calls by the same name. Their code lives elsewhere, so reaching them from here
+takes ${(0, ui_1.bold)('--project <id>')}, which is printed next to each.
+
+${(0, ui_1.bold)('invoke')} calls it exactly the way the application does: the project token plus a
+visitor pass 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)
   --data-file body.json   the same body from a file

package/dist/text-file.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.readTextFile = readTextFile;
+exports.readExactTextFile = readExactTextFile;
 const node_fs_1 = require("node:fs");
 const node_util_1 = require("node:util");
 const errors_1 = require("./errors");
@@ -14,8 +15,19 @@ function readTextFile(path, missingHint) {
         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';
+    // trim() also drops the BOM kept by ignoreBOM: U+FEFF is whitespace in JS.
+    return decode(bytes, encoding, path).trim();
+}
+/**
+ * A file hashed by its exact text, so nothing may be stripped: a dropped BOM or trailing
+ * newline changes the checksum of a migration that is already applied.
+ */
+function readExactTextFile(path) {
+    return decode((0, node_fs_1.readFileSync)(path), 'utf-8', path);
+}
+function decode(bytes, encoding, path) {
     try {
-        return new node_util_1.TextDecoder(encoding, { fatal: true }).decode(bytes).trim();
+        return new node_util_1.TextDecoder(encoding, { fatal: true, ignoreBOM: true }).decode(bytes);
     }
     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.32.0';
+exports.CLI_VERSION = '0.34.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.32.0",
+  "version": "0.34.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.32.0, so the copy you are reading can be older than
+These instructions ship with xflow CLI 0.34.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
@@ -48,8 +48,8 @@ the error points away from the cause. The sections below carry the details.
 3. Never delete a `functions/<name>/` directory unless the user asked for that
    function to go. The next deploy removes it from the cloud together with its
    schedules, and a function created again later gets a different address.
-4. An already applied migration is never re-run, so editing its file changes
-   nothing. A schema change is always a new file.
+4. An already applied migration is never re-run, and `xflow db migrate` refuses a
+   name it already holds with different content. A schema change is always a new file.
 5. When inserts start failing with `db_write_locked`, the database is over its plan size
    and Postgres itself refuses. Reads and deletes keep working, so the fix is a migration
    that deletes data, never a rewrite of the SQL. Write comes back within the hour.
@@ -280,8 +280,9 @@ bundle is built they already exist.
 
 ### Who is calling
 
-A function answers only to a member of the organization who has access to that project.
-The platform issues a short-lived pass when it opens the application, the wrapper checks it
+A function answers a member of the organization who has access to that project, an outside
+service holding a key of that function, and, when the code opens it, anyone at all. The
+platform issues a short-lived pass when it opens the application, the wrapper checks it
 with the platform on every call, and the handler receives the answer in `event.xflow`:
 
 ```js
@@ -346,6 +347,10 @@ in the interface, and removing the line and deploying closes it again.
 `xflow functions list` shows who can reach each function: `in-app only` (answers only inside
 the application), `external (N keys)` (a human issued external access), `public` (the code
 opened it), and the address of every deployed function. Key values are never shown there.
+Under the table it names the standalone functions of the organization this project calls by
+the same name, each with the `--project` id its code lives in: that list and the table
+together are everything `xflow.functions.invoke` reaches from here. A deploy prints the
+address of every function it left open, so a page needs no second command to find it.
 
 ## Secrets and connected accounts
 
@@ -450,8 +455,10 @@ xflow functions logs report                # empty output means it never crashed
 
 Schema changes are files: `migrations/0001_init.sql`, `migrations/0002_orders.sql`, applied
 in filename order by `xflow db migrate`. `xflow db status` shows what is applied and what
-waits. History lives in the database itself, so an already applied file is never re-run and
-editing it changes nothing: write a new migration instead.
+waits. History lives in the database itself, and the database can be shared with other
+projects of the organization, so a migration name is taken once for all of them: `migrate`
+refuses a name that is already applied with different content. Never edit an applied file,
+write a new migration instead.
 
 The browser never reaches the database directly. The app reads and writes through a cloud
 function, and inside the handler the connection string is already there:
@@ -623,6 +630,10 @@ platform: pick a page when the audience is outside the organization.
 - Static files only: HTML, CSS, JS, images, fonts, PDF, audio, video. No server code, database
   or functions on a page. Upload what the build writes (`dist`), never a folder with
   `package.json`. At most 5 MB zipped, 25 MB unpacked, 1000 files.
+- Everything a page shows travels inside the page. File storage of a project is not an
+  option: its addresses open only for a signed-in member with access to that project, so in a
+  page they give a visitor nothing. Heavy media has to fit those caps or be hosted elsewhere,
+  and that is worth saying before a landing page is designed around a video.
 - A page that needs a backend (a form, a lookup) calls a cloud function of a project that
   declares `exports.access = 'public'` (see «Who is calling»): the page fetches the address
   from `xflow functions list` directly, with no key and no header. The function lives in a
@@ -630,6 +641,8 @@ platform: pick a page when the audience is outside the organization.
 - Everything in a page is readable by every visitor. Never put a key, token or password into
   it: a known key format gets the upload refused, anything else simply leaks.
 - Search engines are asked not to index pages: do not promise SEO.
+- The tab icon is the platform's on every page: the upload drops any `<link rel="…icon…">` the
+  files carry and puts the XFlow one in. Do not spend a request on a favicon of your own.
 - The MCP `pages` tool uploads one self-contained HTML document up to 150 KB.
 - Pages take the key of the whole organization, the one `xflow login` issues; a key scoped to
   projects is refused, and that refusal is not yours to fix. Switching a page off and deleting it