@getxflow/cli 0.9.0 → 0.9.1

package/README.md

@@ -20,7 +20,7 @@ else's code belongs next to it.
 | `org` / `org switch` | organizations with a stored key, and which one this folder works with |
 | `init` / `link` / `templates` | new project, link a folder to an existing one, which templates there are |
 | `status` / `pull` | state of the sources on the server and fetching them back |
-| `deploy` / `publish` / `rollback` / `deployments` | build, publish, roll back, version history |
+| `deploy` / `publish` / `rollback` / `deployments` | build, publish, serve earlier pages, version history |
 | `db status` / `db migrate` | migrations from `migrations/*.sql` with a gate on destructive ones |
 | `db schema` / `db query` | tables and columns, reading data in a read-only transaction |
 | `functions list` | cloud functions of the project from `functions/<name>/index.ts`, shipped by `deploy` |

package/dist/commands/deploy.js

@@ -18,6 +18,8 @@ const sources_1 = require("./sources");
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /** Slightly longer than the platform's own build timeout. */
 const WAIT_LIMIT_MS = 16 * 60_000;
+/** Said the same way with a terminal and without one. */
+const REMOVAL_IS_FINAL = 'Removal is final: a function created again later gets a different address, schedules included';
 /** Print every check violation at once. */
 function reportIssues(e) {
     const issues = e.issues ?? [];
@@ -81,13 +83,19 @@ async function startBuild(client, projectId, revision, allowRemovals) {
     catch (e) {
         if (e instanceof api_1.ApiError && e.issues?.length)
             reportIssues(e);
-        const removing = e instanceof api_1.ApiError && e.code === 'confirm_required' ? (e.removing ?? []) : [];
-        // No terminal (CI, an agent): the flag is the only way to say yes, and the
-        // platform message already names it.
-        if (removing.length === 0 || process.stdin.isTTY !== true || process.stderr.isTTY !== true)
+        if (!(e instanceof api_1.ApiError) || e.code !== 'confirm_required')
             throw e;
+        const removing = e.removing ?? [];
+        if (removing.length === 0)
+            throw e;
+        // No terminal (CI, an agent): the flag is the only way to say yes. The platform
+        // hint names the API field, so translate it into the flag this CLI accepts.
+        if (process.stdin.isTTY !== true || process.stderr.isTTY !== true) {
+            throw new errors_1.CliError(e.message, `${REMOVAL_IS_FINAL}. If that is intended, retry with --allow-removals. ` +
+                'If it is not, bring the functions/<name>/index.ts directories back');
+        }
         (0, ui_1.warn)(`Gone from the sources, the build would remove them: ${removing.join(', ')}`);
-        (0, ui_1.note)((0, ui_1.dim)('  Removal is final: a function created again later gets a different address, schedules included'));
+        (0, ui_1.note)((0, ui_1.dim)(`  ${REMOVAL_IS_FINAL}`));
         const answer = await (0, prompt_1.select)('Remove them from the cloud?', [
             { label: 'No, stop here', hint: 'bring the functions/<name>/index.ts directories back' },
             { label: 'Yes, remove and build', hint: removing.join(', ') },
@@ -158,7 +166,9 @@ async function deploy(args) {
     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)('  Show it to visitors: xflow publish'));
+    (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'));
+    (0, ui_1.note)((0, ui_1.dim)('  Show the new pages to visitors: xflow publish'));
 }
 async function publish() {
     const { root, config } = (0, config_1.requireProject)();
@@ -169,9 +179,11 @@ async function publish() {
         (0, ui_1.ok)('This version is already published');
     }
     else {
-        (0, ui_1.ok)(`Version ${result.deploy_id} published: visitors see it now`);
+        (0, ui_1.ok)(`Version ${result.deploy_id} published: visitors see its pages now`);
     }
     (0, ui_1.out)(result.project_url);
+    (0, ui_1.note)((0, ui_1.dim)('  Publishing moves the pages only. Cloud functions are one per project: visitors'));
+    (0, ui_1.note)((0, ui_1.dim)('  have been running the code of the last xflow deploy since it finished'));
 }
 async function rollback(args) {
     const { root, config } = (0, config_1.requireProject)();
@@ -181,12 +193,15 @@ async function rollback(args) {
     }
     const client = await (0, session_1.connectProject)(root, config);
     const result = await (0, api_1.apiJson)(client, `/api/v1/projects/${config.projectId}/rollback`, { method: 'POST', body: { deploy_id: deployId } });
-    (0, ui_1.ok)(`The dev version of the project is switched to ${result.deploy_id}`);
+    (0, ui_1.ok)(`The project now serves the pages of build ${result.deploy_id}`);
     (0, ui_1.out)(result.project_url);
+    (0, ui_1.note)((0, ui_1.dim)('  Only the pages came back. Cloud functions and the database are one per project:'));
+    (0, ui_1.note)((0, ui_1.dim)('  they are not versioned and stay as they are now'));
     if (result.revision !== null) {
-        (0, ui_1.note)((0, ui_1.dim)(`  The code of this version: xflow pull --revision ${result.revision} --into ./v${result.deploy_id}`));
+        (0, ui_1.note)((0, ui_1.dim)(`  The code of this build: xflow pull --revision ${result.revision} --into ../v${result.deploy_id}`));
+        (0, ui_1.note)((0, ui_1.dim)('  Building that code over the current one is a separate step: it overwrites the server revision'));
     }
-    (0, ui_1.note)((0, ui_1.dim)('  Visitors see it only after xflow publish'));
+    (0, ui_1.note)((0, ui_1.dim)('  Visitors see these pages only after xflow publish'));
 }
 async function deployments() {
     const { root, config } = (0, config_1.requireProject)();
@@ -203,4 +218,6 @@ async function deployments() {
         (0, ui_1.formatAge)(d.deployed_at ?? d.created_at),
         [d.is_dev ? (0, ui_1.bold)('dev') : '', d.is_live ? (0, ui_1.bold)('live') : ''].filter(Boolean).join(' '),
     ]));
+    (0, ui_1.note)((0, ui_1.dim)('  Serve the pages of an earlier build: xflow rollback <number>'));
+    (0, ui_1.note)((0, ui_1.dim)('  Fetch the code of a build: xflow pull --revision <its revision> --into ../copy'));
 }

package/dist/commands/sources.js

@@ -66,7 +66,7 @@ async function confirmForce(client, projectId, server, local) {
         (0, ui_1.warn)('Could not read the server copy: the list of disappearing files is unavailable');
     }
     (0, ui_1.note)('');
-    const confirmed = await (0, ui_1.confirmWord)(`This overwrites work that is not yours, with no way to recover it from the platform.`, card.name);
+    const confirmed = await (0, ui_1.confirmWord)(`The server revision will be replaced by the contents of this folder. Anything newer on the platform goes away, and it cannot be recovered from here.`, card.name);
     if (!confirmed)
         throw new errors_1.CliError('Cancelled');
 }
@@ -175,9 +175,12 @@ async function status() {
     const client = await (0, session_1.connectProject)(root, config);
     const tree = prepareTree(root, config);
     const state = (0, config_1.readState)(root);
-    const [card, server] = await Promise.all([
+    const [card, server, history] = await Promise.all([
         (0, api_1.apiJson)(client, `/api/v1/projects/${config.projectId}`),
         latestRevision(client, config.projectId),
+        // History only decorates the output, so its failure must not take the command
+        // down with it: without it the line below simply says less.
+        (0, api_1.apiJson)(client, `/api/v1/projects/${config.projectId}/deployments`).catch(() => ({ deployments: [] })),
     ]);
     (0, ui_1.out)(`${(0, ui_1.bold)(card.name)}  ${(0, ui_1.dim)(card.id)}`);
     (0, ui_1.out)('');
@@ -200,9 +203,28 @@ async function status() {
             (0, ui_1.note)((0, ui_1.dim)('  Send and build them: xflow deploy'));
         }
     }
+    // Which revision the built version came from. Silent when there is nothing to say:
+    // the row fell out of the truncated history, it predates revisions, or a build is
+    // running right now and the answer would change in a minute.
+    const running = history.deployments.some((d) => ['pending', 'building', 'uploading'].includes(d.status));
+    const devRow = running ? null : (history.deployments.find((d) => d.is_dev) ?? null);
+    const builtFrom = devRow?.revision ?? null;
+    // The dev address holds a build that is not the newest one: the project was put back
+    // on earlier pages on purpose. Saying "the code is newer" here would name the wrong
+    // reason and send the developer to build what is already built.
+    const newest = history.deployments.find((d) => d.status === 'deployed');
+    const rolledBack = devRow?.status === 'deployed' && !!newest && newest.deploy_id !== devRow.deploy_id;
     (0, ui_1.out)('');
-    (0, ui_1.out)(`Built version:    ${card.dev_deploy_id ?? '(no build)'}`);
+    (0, ui_1.out)(`Built version:    ${card.dev_deploy_id ?? '(no build)'}` +
+        (builtFrom !== null ? ` from revision ${builtFrom}` : ''));
     (0, ui_1.out)(`Visitors see:     ${card.live_deploy_id ?? '(never published)'}`);
+    if (rolledBack) {
+        (0, ui_1.note)((0, ui_1.dim)('  The project serves the pages of an earlier build: a newer one is in the history'));
+        (0, ui_1.note)((0, ui_1.dim)('  Cloud functions and the database are not versioned and stay as they are'));
+    }
+    else if (builtFrom !== null && server && builtFrom < server.revision) {
+        (0, ui_1.note)((0, ui_1.dim)(`  The built version is behind the sources: revision ${builtFrom} against ${server.revision} on the server`));
+    }
     // Two different problems, two different fixes: an expiring token is renewed by
     // any build, a revoked one is not renewed by anything until a human reconnects
     // the account. Telling them apart saves a pointless rebuild.

package/dist/help.js

@@ -27,7 +27,7 @@ ${(0, ui_1.bold)('Sources')}
 ${(0, ui_1.bold)('Releasing')}
   xflow deploy [--no-push]        send the code, ship the functions, build on the platform
   xflow publish                   show the dev version to visitors
-  xflow rollback <version number> return the project to an earlier version
+  xflow rollback <version number> serve the pages of an earlier build
   xflow deployments               version history
 
 ${(0, ui_1.bold)('Functions')}
@@ -396,11 +396,17 @@ is not a formality: your own palette on top of them looks foreign inside the pla
 The order: the project is created on the platform first, because without it there is
 nowhere to get the token for .env. If writing the files fails, the project stays empty
 and the CLI explains how to pick it up with the link command.`,
-    rollback: `${(0, ui_1.bold)('xflow rollback')} <version number>: return an earlier build
+    rollback: `${(0, ui_1.bold)('xflow rollback')} <version number>: serve the pages of an earlier build
 
-Switches the project to the chosen build. Only the build comes back: the sources stay
-at their own revision, and returning them is a separate decision
-(${(0, ui_1.bold)('xflow pull --revision N --into ./old-version')}).
+Points the project at the pages of that build. ${(0, ui_1.bold)('Only the pages come back.')} Cloud
+functions and the database are one per project: they are not versioned, they are shared
+with the published application, and they stay exactly as they are now. A page from August
+will be talking to today's functions.
 
-Visitors keep seeing the published version until ${(0, ui_1.bold)('xflow publish')} is run.`,
+The sources stay at their own revision too. Fetching the code of that build is a separate
+command (${(0, ui_1.bold)('xflow pull --revision N --into ../old-version')}, keep the copy outside the
+project folder). Building that code over the current one is a further, deliberate step: it
+replaces the server revision, and whatever is newer on the platform goes away.
+
+Visitors keep seeing the published pages until ${(0, ui_1.bold)('xflow publish')} is run.`,
 };

package/dist/ui.js

@@ -119,7 +119,7 @@ function offerBrowser(url) {
 async function confirmWord(question, expected) {
     if (!process.stdin.isTTY) {
         fail('Confirmation is only possible in an interactive terminal');
-        note((0, exports.dim)('  In CI this is the right behaviour: a version conflict has to fail the build rather than overwrite work that is not yours'));
+        note((0, exports.dim)('  In CI this is the right behaviour: a version conflict has to fail the build rather than overwrite what the platform holds'));
         return false;
     }
     const rl = (0, node_readline_1.createInterface)({ input: process.stdin, output: process.stderr });

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.9.0';
+exports.CLI_VERSION = '0.9.1';
 /** 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.9.0",
+  "version": "0.9.1",
   "description": "CLI for the XFlow platform: source sync, deployment and publishing of applications",
   "license": "UNLICENSED",
   "engines": {
@@ -14,7 +14,8 @@
     "skills"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
     "prepublishOnly": "npm run build"
   },
   "publishConfig": {

package/skills/xflow/SKILL.md

@@ -73,12 +73,23 @@ restored within an hour of the data going back under the limit.
 6. `xflow publish` makes that same version visible to visitors.
 
 The split is deliberate: shipping a build and showing it are two separate decisions.
-Until `publish` runs, visitors keep seeing the previous version. The one exception is
+Until `publish` runs, visitors keep seeing the previous pages. The one exception is
 the very first version of a project: it publishes automatically, since there is no
 live version to protect yet.
 
-Rolling back: `xflow deployments` lists the version history, `xflow rollback <id>`
-points the project back at an earlier build. Sources stay on their own revision.
+**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
+application the moment it finishes, before any `publish`, and `publish` moves the pages
+only. Tell the user this when a deploy touches `functions/`: there is no staging step for
+server code.
+
+Rolling back: `xflow deployments` lists the version history, `xflow rollback <id>` points
+the project at the pages of an earlier build. Only the pages come back — those pages then
+talk to today's functions. The sources stay on their own revision; fetching the code of
+that build is a separate command (`xflow pull --revision N --into ../old-version`, keep the
+copy outside the project folder). Building that code over the current one is a further,
+deliberate step: it replaces the server revision, needs `--force`, and asks a human to type
+the project name, so you cannot do it on your own.
 
 The platform keeps the **last 30 successful builds**. Older ones are deleted, files and
 history row alike, and rolling back to them stops working. That is rollback depth, not a

package/dist/commands/update.test.js

@@ -1,34 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-const strict_1 = __importDefault(require("node:assert/strict"));
-const node_test_1 = require("node:test");
-const update_1 = require("./update");
-/**
- * The price of a mistake here is npm running over a pnpm or bun installation, which
- * leaves two copies and a user who cannot tell which one answers. Path shapes only,
- * the rest of the command is a run, not a rule.
- */
-(0, node_test_1.test)('a global npm prefix is an ordinary install', () => {
-    strict_1.default.equal((0, update_1.classifyPath)('C:\\Users\\me\\AppData\\Roaming\\npm\\node_modules\\@getxflow\\cli\\dist'), 'node_modules');
-    strict_1.default.equal((0, update_1.classifyPath)('/usr/local/lib/node_modules/@getxflow/cli/dist'), 'node_modules');
-    strict_1.default.equal((0, update_1.classifyPath)('/home/me/.npm-global/lib/node_modules/@getxflow/cli/dist'), 'node_modules');
-});
-(0, node_test_1.test)('npm as a path segment is not pnpm', () => {
-    strict_1.default.notEqual((0, update_1.classifyPath)('C:\\Users\\me\\AppData\\Roaming\\npm\\node_modules\\@getxflow\\cli\\dist'), 'pnpm');
-});
-(0, node_test_1.test)('other package managers are recognized by their own folders', () => {
-    strict_1.default.equal((0, update_1.classifyPath)('/home/me/.local/share/pnpm/global/5/node_modules/@getxflow/cli/dist'), 'pnpm');
-    strict_1.default.equal((0, update_1.classifyPath)('/home/me/project/node_modules/.pnpm/@getxflow+cli@0.6.0/node_modules/@getxflow/cli/dist'), 'pnpm');
-    strict_1.default.equal((0, update_1.classifyPath)('/home/me/.bun/install/global/node_modules/@getxflow/cli/dist'), 'bun');
-    strict_1.default.equal((0, update_1.classifyPath)('/home/me/project/.yarn/cache/@getxflow-cli/dist'), 'yarn');
-});
-(0, node_test_1.test)('an npx run is a cached copy, not an installation', () => {
-    strict_1.default.equal((0, update_1.classifyPath)('/home/me/.npm/_npx/8f1a2b/node_modules/@getxflow/cli/dist'), 'npx');
-});
-(0, node_test_1.test)('without node_modules the code runs from a checkout', () => {
-    strict_1.default.equal((0, update_1.classifyPath)('C:\\cursor\\xflow 2.0\\cli\\dist'), 'checkout');
-    strict_1.default.equal((0, update_1.classifyPath)('/home/me/xflow/cli/src'), 'checkout');
-});

package/dist/limits.test.js

@@ -1,25 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-const node_test_1 = require("node:test");
-const strict_1 = __importDefault(require("node:assert/strict"));
-const limits_1 = require("./limits");
-(0, node_test_1.test)('a counted limit reads as a tally', () => {
-    const line = (0, limits_1.limitLine)({ code: 'limit_functions', used: 29, limit: 29 });
-    strict_1.default.equal(line, 'Plan limit: cloud functions, 29 of 29 used. Repeating the same command will not help.');
-});
-(0, node_test_1.test)('an interval reads as a frequency, not as a tally', () => {
-    const line = (0, limits_1.limitLine)({ code: 'limit_schedule_interval', used: 5, limit: 60 });
-    strict_1.default.match(line, /every 5 min against a 60 min minimum/);
-    strict_1.default.doesNotMatch(line, /used/);
-});
-(0, node_test_1.test)('a refusal without numbers stays a plain sentence', () => {
-    const line = (0, limits_1.limitLine)({ code: 'plan_no_schedules' });
-    strict_1.default.equal(line, 'Plan limit: schedules. Repeating the same command will not help.');
-});
-(0, node_test_1.test)('an unknown code falls back to the code itself', () => {
-    const line = (0, limits_1.limitLine)({ code: 'limit_unheard_of' });
-    strict_1.default.match(line, /Plan limit: limit_unheard_of\./);
-});