@getxflow/cli 0.10.6 → 0.11.1

package/README.md

@@ -7,7 +7,7 @@ npm i -g @getxflow/cli
 xflow login
 xflow init my-app
 cd my-app && npm install
-xflow deploy
+xflow deploy -m "First version"
 xflow publish
 ```
 

package/dist/args.js

@@ -27,7 +27,8 @@ function parseArgs(argv) {
     const words = [];
     const flags = {};
     for (let i = 0; i < argv.length; i++) {
-        const token = argv[i];
+        // -m is what git taught everyone to type for a message; honour it as an alias.
+        const token = argv[i] === '-m' ? '--message' : argv[i];
         if (token === '--') {
             words.push(...argv.slice(i + 1));
             break;

package/dist/commands/auth.js

@@ -158,5 +158,11 @@ async function whoami() {
                 ? `yes, no more often than one run every ${interval} min`
                 : 'yes'
             : 'no'}`);
+        if (typeof me.features.function_timeout_s === 'number') {
+            (0, ui_1.out)(`Function time cap: ${me.features.function_timeout_s} s per call, applied on the next build`);
+        }
+        if (typeof me.features.builds_concurrent === 'number') {
+            (0, ui_1.out)(`Concurrent builds: ${me.features.builds_concurrent}`);
+        }
     }
 }

package/dist/commands/db.js

@@ -177,14 +177,13 @@ async function dbQuery(args) {
     }
     (0, ui_1.table)([data.columns, ...data.rows.map((row) => data.columns.map((column) => cell(row[column])))]);
     if (data.truncated) {
-        // "raise --limit" used to be the whole advice, and for a long time it was
-        // impossible to follow: the ceiling and the default were the same number, so
-        // the flag could only ask for less. Now it can ask for more, and the line
-        // says so only while there is room left.
+        // No exact total here: the platform stops reading at limit + 1 rows, so all
+        // it knows is that more exist. The "raise --limit" advice shows only while
+        // the flag still has room below the ceiling.
         const room = data.limit !== undefined && data.limit_max !== undefined && data.limit < data.limit_max;
         (0, ui_1.note)((0, ui_1.dim)(room
-            ? `  Shown ${data.rows.length} of ${data.total}: raise --limit (up to ${data.limit_max}), or narrow the query`
-            : `  Shown ${data.rows.length} of ${data.total}: narrow the query, with a where clause or an offset`));
+            ? `  Shown the first ${data.rows.length} rows, more exist: raise --limit (up to ${data.limit_max}), or narrow the query`
+            : `  Shown the first ${data.rows.length} rows, more exist: narrow the query, with a where clause or an offset`));
     }
 }
 async function dbMigrate(args) {

package/dist/commands/deploy.js

@@ -72,12 +72,12 @@ async function refreshFunctionsEnv(root, client, projectId) {
  * refuses such a build until the caller says yes, and the question is asked
  * here, before the build starts, rather than reported once it already has.
  */
-async function startBuild(client, projectId, revision, allowRemovals) {
+async function startBuild(client, projectId, revision, allowRemovals, comment) {
     const path = `/api/v1/projects/${projectId}/builds`;
     try {
         return await (0, api_1.apiJson)(client, path, {
             method: 'POST',
-            body: { revision, allow_removals: allowRemovals },
+            body: { revision, allow_removals: allowRemovals, comment },
         });
     }
     catch (e) {
@@ -104,7 +104,7 @@ async function startBuild(client, projectId, revision, allowRemovals) {
             throw new errors_1.CliError('The build did not start', 'Nothing was removed');
         return (0, api_1.apiJson)(client, path, {
             method: 'POST',
-            body: { revision, allow_removals: true },
+            body: { revision, allow_removals: true, comment },
         });
     }
 }
@@ -120,7 +120,29 @@ async function startBuild(client, projectId, revision, allowRemovals) {
 async function assertBuildAllowed(client, projectId) {
     await (0, api_1.apiJson)(client, `/api/v1/projects/${projectId}/builds?check=plan`);
 }
+/** Keep in sync with the builds route on the platform. */
+const MAX_COMMENT_LENGTH = 200;
+/** Control and bidi-override characters: they spoof terminals, not comments. */
+const COMMENT_CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f\u200e\u200f\u202a-\u202e\u2066-\u2069]/g;
+/**
+ * The version comment, checked before anything goes up: a refusal after the push
+ * would leave the project with a revision newer than its build for no good reason.
+ */
+function requireComment(args) {
+    const comment = ((0, args_1.flagString)(args, 'message') ?? '')
+        .replace(/\s+/g, ' ')
+        .replace(COMMENT_CONTROL_CHARS, '')
+        .trim();
+    if (!comment) {
+        throw new errors_1.CliError('Every version needs a comment saying what changed in it', 'Add -m: xflow deploy -m "Cart and card payments". One short line, written in the language the user speaks: it names this version in the history');
+    }
+    if (comment.length > MAX_COMMENT_LENGTH) {
+        throw new errors_1.CliError(`The version comment is too long: ${MAX_COMMENT_LENGTH} characters at most`, 'One short line about what changed in this version is enough');
+    }
+    return comment;
+}
 async function deploy(args) {
+    const comment = requireComment(args);
     const { root, config } = (0, config_1.requireProject)();
     const client = await (0, session_1.connectProject)(config.projectId, root, config);
     let revision;
@@ -137,7 +159,7 @@ async function deploy(args) {
         revision = (await (0, sources_1.pushSources)(root, config, client, { force: (0, args_1.flagBool)(args, 'force') })).revision;
     }
     (0, ui_1.step)(`Building on the platform from revision ${revision}`);
-    const started = await startBuild(client, config.projectId, revision, (0, args_1.flagBool)(args, 'allow-removals'));
+    const started = await startBuild(client, config.projectId, revision, (0, args_1.flagBool)(args, 'allow-removals'), comment);
     if (started.removed_functions?.length) {
         (0, ui_1.warn)(`Removed from the cloud, gone from the sources: ${started.removed_functions.join(', ')}`);
     }
@@ -213,6 +235,8 @@ async function deployments(args) {
         d.revision !== null ? `revision ${d.revision}` : 'no revision',
         d.status === 'deployed' ? 'ready' : d.status,
         (0, ui_1.formatAge)(d.deployed_at ?? d.created_at),
+        // Plain text only: a padded cell with ANSI codes would skew every column after it.
+        d.comment && d.comment.length > 60 ? `${d.comment.slice(0, 59)}…` : (d.comment ?? ''),
         [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>'));

package/dist/commands/functions.js

@@ -67,6 +67,10 @@ async function functionsInvoke(args) {
     catch {
         (0, ui_1.note)((0, ui_1.dim)('  Could not get a visitor pass: calling with the project token only'));
     }
+    // The cap the deployed version actually carries, not the plan's current one:
+    // they diverge until the next build. Null means deployed before the platform
+    // recorded caps, that is with 90.
+    const capS = fn.execution_timeout_s ?? 90;
     const started = Date.now();
     let response;
     try {
@@ -78,8 +82,8 @@ async function functionsInvoke(args) {
                 ...(pass ? { 'X-Project-Pass': pass } : {}),
             },
             body: sendsBody ? (data ?? '{}') : undefined,
-            // Wait past the function's own 90 s cap to see its timeout, not ours.
-            signal: AbortSignal.timeout(100_000),
+            // Wait past the function's own cap to see its timeout, not ours.
+            signal: AbortSignal.timeout((capS + 10) * 1000),
         });
     }
     catch (e) {

package/dist/flags.js

@@ -73,7 +73,7 @@ const KNOWN = {
     'storage remove': ['folder', 'yes', 'project'],
     status: [],
     pull: ['into', 'force', 'revision'],
-    deploy: ['no-push', 'force', 'allow-removals'],
+    deploy: ['no-push', 'force', 'allow-removals', 'message'],
     publish: ['project'],
     rollback: ['project'],
     deployments: ['project'],

package/dist/help.js

@@ -57,7 +57,7 @@ ${(0, ui_1.bold)('Files')}
                                   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 deploy -m "what changed"  send the code, ship the functions, build on the platform
   xflow publish                   show the dev version to visitors
   xflow rollback <version number> serve the pages of an earlier build
   xflow deployments               version history
@@ -253,7 +253,8 @@ ${(0, ui_1.bold)('console.log')} lines of that call) and sends it to the platfor
 write nothing, otherwise every request would pay for it in latency.
 
 What never reaches this list: a crash while the module is starting (the function
-never gets as far as the wrapper), going over 90 seconds, and running out of memory.
+never gets as far as the wrapper), going over the execution time cap of the plan
+(${(0, ui_1.bold)('xflow whoami')} names it), and running out of memory.
 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
@@ -467,6 +468,9 @@ Three steps: sending the sources, shipping the cloud functions, building the app
 The build command and the output directory come from xflow.json (npm run build and dist
 by default).
 
+  -m <text>          the version comment, required: one short line in the language the
+                     user speaks, saying what changed. It names the version in the
+                     history (--message is the long form)
   --no-push          do not send sources, build from the latest server revision
   --force            allow overwriting the server revision while sending
   --allow-removals   agree in advance to remove the functions gone from the sources

package/dist/limits.js

@@ -5,8 +5,11 @@ exports.limitLine = limitLine;
 exports.quotaRows = quotaRows;
 const DENIAL_LABELS = {
     limit_projects: 'projects',
+    limit_databases: 'databases',
+    limit_connections: 'active connector connections',
     limit_functions: 'cloud functions',
     limit_builds: 'builds this month',
+    limit_builds_concurrent: 'builds running at once',
     limit_seats: 'seats in the organization',
     limit_schedule_interval: 'schedule frequency',
     db_write_locked: 'database volume, writes are off',
@@ -29,6 +32,8 @@ function limitLine(detail) {
 }
 const QUOTA_ORDER = [
     'projects',
+    'databases',
+    'connections',
     'functions',
     'developers',
     'members',
@@ -39,6 +44,8 @@ const QUOTA_ORDER = [
 ];
 const QUOTA_LABELS = {
     projects: 'Projects',
+    databases: 'Databases',
+    connections: 'Active connections',
     functions: 'Cloud functions',
     developers: 'Developers',
     members: 'Staff',

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

package/skills/xflow/SKILL.md

@@ -24,7 +24,7 @@ contains the fix.
 
 ## Keeping these instructions current
 
-These instructions ship with xflow CLI 0.10.6. They travel inside the package, so the copy
+These instructions ship with xflow CLI 0.11.1. They travel inside the package, so the copy
 you are reading can be older than the CLI answering your commands, and nothing about that
 is visible in the text itself.
 
@@ -65,11 +65,23 @@ the error points away from the cause. The sections below carry the details.
 
 ## Plan limits
 
-The organization runs on a plan with finite limits: projects, cloud functions, developer
-and staff seats, database and file storage, function minutes per month, plus schedules and
-how often they may run. `xflow whoami` prints every one of them next to what is already
+The organization runs on a plan with finite limits: projects, databases, cloud functions,
+active connector connections, developer and staff seats, database and file storage,
+function minutes and builds per month, builds running at once, plus schedules and how
+often they may run. `xflow whoami` prints every one of them next to what is already
 used, and reading it before a long task is cheaper than hitting a wall mid-way.
 
+Two of them deserve a word. A database outlives its project (deleting a project only
+detaches it), so a refused database on a small plan usually means an orphan: the fix is
+deleting the unused database in the "Data" section of the web interface, not renaming
+anything. Connector connections are counted while active: switching an unused connection
+off in the web interface frees the seat without deleting it.
+
+The plan also caps how long one call of a cloud function may run. The cap is written
+into the function when it is deployed, so a plan change reaches the cloud only with the
+next `xflow deploy` of each project, in both directions. `xflow whoami` names the plan's
+cap; what a deployed function actually carries is what it was last deployed with.
+
 The same output names the rights of your own key, which is the other half of the answer:
 destroying data in a migration, deleting files from storage and linking a connected
 account each need a right that is off by default. Reading that line first turns a refusal
@@ -96,8 +108,10 @@ back within an hour of the data going under the limit.
    script, then `npx tsc --noEmit`).
 3. `npm run build` if the change is substantial. The platform builds again in its own
    sandbox, on one Node version for everyone, so this is only a fast way to see errors early.
-4. `xflow deploy` sends the sources, ships the cloud functions and builds the application
-   on the platform, printing each phase and the six-digit number of the version it built.
+4. `xflow deploy -m "what changed"` sends the sources, ships the cloud functions and
+   builds the application on the platform, printing each phase and the six-digit number
+   of the version it built. The comment is required: one short line in the language the
+   user speaks, it names this version in the history.
 5. Give the user the project link the CLI printed and let them look. Do not open a
    browser for them.
 6. `xflow publish` makes that same version visible to visitors.
@@ -221,6 +235,13 @@ enforces this, but a project where every function answers its own way costs an a
 on every call. Branch the frontend on `error.code`, never on `error.message`: wording
 gets rewritten on any edit, a code does not.
 
+How a non-2xx answer reaches the page depends on the generation of `src/lib/xflow.ts`
+in the project, so look at that file before writing the catch: a copy that declares
+`XFlowError` throws it carrying `code` and `status`, and a copy that says nothing about
+errors is older and throws a plain `Error` whose message is all there is. In an older
+project, a function that wants its error text seen on the page answers `200` with
+`{ success: false, error }` in the body.
+
 The sources are the whole truth about which functions exist. Delete the directory and the
 next deploy would delete the function from the cloud, schedules included, and that cannot be
 undone: a function created again later gets a different address. So never remove a function
@@ -361,7 +382,7 @@ The pieces line up in one pass. From a new function to a verified schedule:
 ```
 xflow env set SMTP_PASSWORD=...            # secrets first: values ride the next deploy
 # write functions/report/index.ts, reading process.env.SMTP_PASSWORD literally
-xflow deploy                               # ships the function, then builds the app
+xflow deploy -m "Nightly report function"  # ships the function, then builds the app
 xflow schedules set report "0 3 ? * * *" --payload '{"mode":"full"}'   # needs a deployed function
 xflow functions invoke report              # run it once, the way the app would
 xflow functions logs report                # empty output means it never crashed
@@ -467,7 +488,7 @@ for a visitor who is signed in and has access to this project, the same rule tha
 application itself, so it works on your pages and does nothing in an email or on a page
 anyone can open.
 
-Three things bite an upload that otherwise looks right:
+Four things bite an upload that otherwise looks right:
 
 - **A name already taken in that folder is refused before the link is issued.** Pass
   `overwrite: true` to replace the file: the bytes change and the address stays, which is
@@ -477,11 +498,17 @@ Three things bite an upload that otherwise looks right:
   bytes are already up; the platform then removes the object and your table stays clean.
 - **Confirm only after the PUT has finished.** The platform looks the object up in storage
   and takes its real size and content type from there, not from what you declared, so an
-  early `confirm` answers that the file is not there. Send on the PUT the `Content-Type` you
-  named when asking for the link: storage serves the file under the header it received.
+  early `confirm` answers that the file is not there. Send on the PUT exactly the
+  `Content-Type` you named when asking for the link: the link is signed for that header, a
+  different or missing type gets 403, and storage serves the file under it.
+- **Storage takes application assets, not code.** Images, documents, data files, audio,
+  video, fonts and archives pass; pages, scripts and executables (`html`, `js`, `exe`, …)
+  are refused with `forbidden_type` when the link is requested. Both the extension and the
+  declared `content_type` are checked. Application code travels through `xflow deploy`, not
+  through storage.
 
 A refusal comes back as `{ error, code }`. Branch on `code` (`invalid_name`, `file_too_large`,
-`quota_exceeded`, `not_uploaded`, `duplicate_name`, `not_found`, …) and never on the text:
+`quota_exceeded`, `not_uploaded`, `duplicate_name`, `forbidden_type`, `not_found`, …) and never on the text:
 the wording is free to change, the code is not.
 
 What the app may do with files is decided inside that function, because the page in the