@getxflow/cli 0.10.5 → 0.11.0

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/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/commands/projects.js

@@ -100,6 +100,18 @@ async function init(args) {
     (0, ui_1.out)('    npm run dev        # develop');
     (0, ui_1.out)('    xflow deploy       # send the code, build and release');
 }
+/**
+ * Linking is a step, not a task. Without this the agent reports the command as done and
+ * goes quiet, leaving the person in front of a folder: it has to read the skill and come
+ * back with a question instead.
+ */
+function nextAfterLink(skillReady) {
+    (0, ui_1.out)('');
+    (0, ui_1.out)(`  ${(0, ui_1.bold)('Next:')}`);
+    if (skillReady)
+        (0, ui_1.out)(`    read ${skills_1.SKILL_IN_PROJECT}: how this platform is built and shipped`);
+    (0, ui_1.out)('    then ask the user what to build or change, and start there');
+}
 async function link(args) {
     const root = (0, config_1.findProjectRoot)() ?? process.cwd();
     const existing = (0, node_fs_1.existsSync)((0, node_path_1.join)(root, config_1.CONFIG_FILE)) ? (0, config_1.readConfig)(root) : undefined;
@@ -148,11 +160,13 @@ async function link(args) {
         write(dir, '.env', (0, template_1.envFile)(card.project_token, client.apiUrl, card.functions));
         (0, ui_1.note)((0, ui_1.dim)('  Created .env with the project token and the function addresses'));
     }
-    (0, skills_1.installSkillQuietly)(dir);
+    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)}`));
-    if (!fresh)
+    if (!fresh) {
+        nextAfterLink(skillReady);
         return;
+    }
     // A clone without the code is half a clone, and the folder has to remember
     // which revision it works from: without that the first push has nothing to
     // compare against and stops.
@@ -164,11 +178,15 @@ async function link(args) {
     catch (e) {
         if (e instanceof api_1.ApiError && e.status === 404) {
             (0, ui_1.note)((0, ui_1.dim)('  The project has no sources yet: write the code and run xflow deploy'));
+            nextAfterLink(skillReady);
             return;
         }
+        // No next step while the code is missing: the pull has to succeed first.
         (0, ui_1.warn)(`The sources did not arrive: ${e instanceof Error ? e.message : e}`);
         (0, ui_1.note)((0, ui_1.dim)('  The folder is linked, fetch them separately: xflow pull'));
+        return;
     }
+    nextAfterLink(skillReady);
 }
 async function list() {
     const root = (0, config_1.findProjectRoot)();

package/dist/commands/skills.js

@@ -1,5 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKILL_IN_PROJECT = void 0;
+exports.skillCopyPaths = skillCopyPaths;
 exports.replacePointer = replacePointer;
 exports.copyIsStale = copyIsStale;
 exports.staleSkillCopy = staleSkillCopy;
@@ -28,13 +30,25 @@ const AGENTS = [
 const DEFAULT_PROJECT = ['claude', 'cursor', 'codex'];
 const DEFAULT_GLOBAL = ['claude', 'codex', 'universal'];
 const CURSOR_RULE = ['.cursor', 'rules', 'xflow.mdc'];
+/** Written by every default install, so the pointer and the link nudge can both name it. */
+exports.SKILL_IN_PROJECT = '.agents/skills/xflow/SKILL.md';
+/**
+ * Every place inside a project a copy of the skill can live. The archive of sources is
+ * built around this list, so a new agent in the table above is kept out of it by adding
+ * the agent and nothing else.
+ */
+function skillCopyPaths() {
+    const paths = new Set(AGENTS.map((agent) => `${[...agent.project, 'xflow'].join('/')}/`));
+    paths.add(CURSOR_RULE.join('/'));
+    return [...paths];
+}
 /** AGENTS.md is always read, unlike the lazily loaded skill: a short pointer lives there. */
 const POINTER_MARKER = '<!-- xflow-skill -->';
 const POINTER = `${POINTER_MARKER}
 ## XFlow
 
 This project is hosted on the XFlow platform and ships through the \`xflow\` CLI, not
-through a git push. Read \`.agents/skills/xflow/SKILL.md\` before deploying, publishing,
+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\`.
@@ -242,15 +256,21 @@ function defaultIds(base, global) {
     }
     return [...ids];
 }
-/** Best-effort install from init and link: a failure must not break the linking. */
+/**
+ * Best-effort install from init and link: a failure must not break the linking.
+ * Reports whether the skill is in place, so the caller does not send an agent to a
+ * file that was never written.
+ */
 function installSkillQuietly(base) {
     try {
         if (install(base, defaultIds(base, false), false).length > 0) {
             (0, ui_1.note)((0, ui_1.dim)('  The platform instructions are laid out for the AI agent'));
         }
+        return true;
     }
     catch {
         (0, ui_1.note)((0, ui_1.dim)('  Could not lay out the AI agent instructions: xflow skills'));
+        return false;
     }
 }
 function pathLabel(agent, global) {

package/dist/commands/sources.js

@@ -142,7 +142,9 @@ async function downloadRevision(client, projectId, target, revision) {
         (0, ui_1.warn)('The hash of the downloaded tree did not match the server one: the contents may have changed in transit');
     }
     (0, node_fs_1.mkdirSync)(target, { recursive: true });
-    const files = (0, zip_1.dropDirectoryEntries)(entries);
+    // The hash above covers the archive as the server holds it; what lands on disk is the
+    // code, without the skill copies older revisions still carry.
+    const files = (0, zip_1.dropDirectoryEntries)(entries).filter((entry) => !(0, tree_1.isSkillCopy)(entry.path));
     for (const entry of files) {
         const path = (0, node_path_1.join)(target, entry.path);
         (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });

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

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSkillCopy = isSkillCopy;
 exports.loadIgnoreRules = loadIgnoreRules;
 exports.collectFiles = collectFiles;
 exports.treeHash = treeHash;
@@ -7,6 +8,7 @@ exports.heaviest = heaviest;
 const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const skills_1 = require("./commands/skills");
 /** Never sent. */
 const DEFAULT_IGNORE = [
     'node_modules/',
@@ -22,6 +24,10 @@ const DEFAULT_IGNORE = [
     // Compiler cache: rewritten by every local build, so it would make a new
     // revision out of nothing.
     'tsconfig.tsbuildinfo',
+    // The skill ships inside the CLI and is laid out by init and link, so a copy of it
+    // is not project code. Sent once, it comes back with every clone and overwrites the
+    // fresh copy the CLI has just written with the one deployed back then.
+    ...(0, skills_1.skillCopyPaths)(),
 ];
 const IGNORE_FILE = '.xflowignore';
 function globToRegExpSource(pattern) {
@@ -58,6 +64,16 @@ function compileRule(raw) {
     const suffix = dirOnly ? '/' : '($|/)';
     return { re: new RegExp(`${prefix}${source}${suffix}`) };
 }
+const skillRules = (0, skills_1.skillCopyPaths)()
+    .map(compileRule)
+    .filter((rule) => rule !== null);
+/**
+ * The same paths on the way back: revisions deployed before the rule above still carry a
+ * copy, and unpacking it would put a stale skill in front of the agent.
+ */
+function isSkillCopy(path) {
+    return skillRules.some((rule) => rule.re.test(path));
+}
 /** Defaults, the .xflowignore file and the ignore field of xflow.json. */
 function loadIgnoreRules(root, extra = []) {
     const lines = [...DEFAULT_IGNORE, ...extra];

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.5';
+exports.CLI_VERSION = '0.11.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.10.5",
+  "version": "0.11.0",
   "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.5. They travel inside the package, so the copy
+These instructions ship with xflow CLI 0.11.0. 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.
@@ -361,7 +375,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 +481,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 +491,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