@getxflow/cli 0.9.1 → 0.10.1

package/dist/help.js

@@ -3,10 +3,29 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.help = help;
 const ui_1 = require("./ui");
 const version_1 = require("./version");
+/**
+ * A page keyed by something other than the command that leads to it. `xflow help invoke`
+ * is nobody's first guess when the command is `xflow functions invoke`, and a page that
+ * covers a neighbour answers for it too.
+ */
+const ALIASES = {
+    functions: 'invoke',
+    publish: 'deploy',
+    deployments: 'rollback',
+};
 /** Help text. For agents this is the reference documentation. */
 function help(topic) {
-    if (topic && TOPICS[topic]) {
-        (0, ui_1.out)(TOPICS[topic]);
+    if (topic) {
+        const page = TOPICS[ALIASES[topic] ?? topic];
+        if (page) {
+            (0, ui_1.out)(page);
+            return;
+        }
+        // Falling through to the full help here is what this used to do, and it reads as an
+        // answer: the agent asked about one command and got the whole screen back, with no
+        // sign that the page it asked for does not exist.
+        (0, ui_1.out)(`No page for "${topic}". Pages: ${Object.keys(TOPICS).sort().join(', ')}
+Every command with a line of its own: xflow help`);
         return;
     }
     (0, ui_1.out)(`${(0, ui_1.bold)('xflow')} ${(0, ui_1.dim)(version_1.CLI_VERSION)} XFlow application hosting
@@ -24,6 +43,14 @@ ${(0, ui_1.bold)('Sources')}
   xflow pull [--into dir] [--revision N]
                                   fetch the sources (the latest revision by default)
 
+${(0, ui_1.bold)('Files')}
+  xflow storage ls [folder]       what the file storage of the project holds
+  xflow storage push <dir> [--to folder] [--replace]
+                                  upload heavy static assets: photos, video, PDFs
+  xflow storage rm <address>      delete one file
+  xflow storage rm --folder <path> --yes
+                                  delete a folder with everything in it
+
 ${(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
@@ -64,6 +91,7 @@ ${(0, ui_1.bold)('Reference')}
   xflow whoami                    whose key this is and what it can do
   xflow logout [--all]            forget the key of the active organization (--all: every one)
   xflow update                    update the CLI itself, and the skill that ships with it
+  xflow --version                 which version is installed
 
 ${(0, ui_1.bold)('Environment')}
   XFLOW_TOKEN                     access key (for CI, instead of xflow login)
@@ -179,6 +207,47 @@ Those show up in the answer to ${(0, ui_1.bold)('xflow functions invoke')}.
 
 Browser errors are collected by ${(0, ui_1.bold)('src/utils/error-logger.ts')} of the template and
 only from released addresses: a local ${(0, ui_1.bold)('npm run dev')} writes nothing here.`,
+    storage: `${(0, ui_1.bold)('xflow storage')}: files of the application
+
+The sources archive is capped at 10 MB and is rebuilt and re-uploaded on every
+deploy, so photos, video and PDFs do not belong in the repository. File storage
+is the place for them: the files sit beside the versions, survive a build, and
+are metered against the plan of the organization.
+
+  xflow storage ls [folder]        what is there, with addresses and sizes
+  xflow storage push ./media --to media
+                                   upload a folder, keeping its structure
+  xflow storage rm <address>       delete one file
+  xflow storage rm --folder photos --yes
+                                   delete a folder with everything in it
+
+  --to <folder>                    where to put it in the project storage
+  --replace                        upload files whose size differs from the stored one
+  --json                           machine-readable output, with every address
+
+${(0, ui_1.bold)('push')} sends only what is missing: a file already stored under the same path and
+size is skipped, so running the command again after a broken connection is cheap.
+A file that differs is left alone unless ${(0, ui_1.bold)('--replace')} is given. Bytes go straight
+into the bucket, they do not pass through the platform.
+
+Addresses are permanent and belong to the record, not to the bytes: replacing a
+file keeps its address, so the links in the code and in the tables of the
+application keep working. That is why there is no delete-and-upload-again.
+
+The address is not public: it is a page of the platform that checks the rights of
+the viewer on every request, so a closed project stops serving its pictures too.
+Use the address as it came back, in ${(0, ui_1.bold)('<img src>')} and in the data of the application.
+
+Dot entries and symbolic links are skipped, and ${(0, ui_1.bold)('.xflowignore')} is not read here:
+those are the rules for the sources, and a media folder is exactly what one is
+asked to put there so it stays out of the archive.
+
+${(0, ui_1.bold)('rm')} needs a right of its own (${(0, ui_1.bold)('Delete files')} in the Developers section of the
+platform), off by default. The reason is the neighbourhood: whatever the users of
+the application uploaded lives in the same folders, and there is no undo. A folder
+first answers with the number of files it holds and deletes only on ${(0, ui_1.bold)('--yes')}.
+
+There is no command back: sources return with ${(0, ui_1.bold)('xflow pull')}, files do not.`,
     env: `${(0, ui_1.bold)('xflow env')}: environment variables of the functions
 
 Keys, passwords and third-party addresses are kept by the platform, not by the

package/dist/state.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.shouldNudge = shouldNudge;
+exports.shouldNudgeSkill = shouldNudgeSkill;
+exports.markSkillNudged = markSkillNudged;
 exports.markNudged = markNudged;
 const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
@@ -33,11 +35,43 @@ function shouldNudge(version) {
         return true;
     return Date.now() - at > NUDGE_INTERVAL_MS;
 }
-/** Best effort: a read-only home folder must not break the command that just worked. */
+/**
+ * Same window, but per stale copy rather than per version. The key carries the CLI
+ * version, so the day a release actually changes the skill the notice speaks again
+ * instead of staying quiet on yesterday's answer.
+ *
+ * A window and not a single "already said it": the copy stays wrong until somebody
+ * refreshes it, and an agent whose session starts tomorrow has to hear about it too.
+ */
+function shouldNudgeSkill(key) {
+    if (process.env.CI)
+        return false;
+    const at = read().skillNudgedAt?.[key];
+    const said = at ? Date.parse(at) : Number.NaN;
+    if (!Number.isFinite(said))
+        return true;
+    return Date.now() - said > NUDGE_INTERVAL_MS;
+}
+/** Entries pile up across versions and folders, so the stale ones go on every write. */
+function markSkillNudged(key) {
+    const now = Date.now();
+    const kept = {};
+    for (const [seen, at] of Object.entries(read().skillNudgedAt ?? {})) {
+        const said = Date.parse(at);
+        if (Number.isFinite(said) && now - said < NUDGE_INTERVAL_MS * 30)
+            kept[seen] = at;
+    }
+    kept[key] = new Date(now).toISOString();
+    write({ skillNudgedAt: kept });
+}
 function markNudged(version) {
+    write({ nudgedVersion: version, nudgedAt: new Date().toISOString() });
+}
+/** Best effort: a read-only home folder must not break the command that just worked. */
+function write(patch) {
     try {
         (0, node_fs_1.mkdirSync)((0, node_path_1.join)((0, node_os_1.homedir)(), '.xflow'), { recursive: true, mode: 0o700 });
-        const state = { ...read(), nudgedVersion: version, nudgedAt: new Date().toISOString() };
+        const state = { ...read(), ...patch };
         (0, node_fs_1.writeFileSync)(statePath(), `${JSON.stringify(state, null, 2)}\n`, 'utf-8');
     }
     catch {

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.1';
+exports.CLI_VERSION = '0.10.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.1",
+  "version": "0.10.1",
   "description": "CLI for the XFlow platform: source sync, deployment and publishing of applications",
   "license": "UNLICENSED",
   "engines": {