@getxflow/cli 0.8.1 → 0.9.1

package/README.md

@@ -17,17 +17,19 @@ else's code belongs next to it.
 | Command | What it does |
 |---|---|
 | `login` / `logout` / `whoami` | sign in through the browser, sign out, whose key this is and what it can do |
-| `init` / `link` | new project, link a folder to an existing one |
+| `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` |
 | `functions invoke` / `functions logs` | call a function, look at its crashes with the stack |
 | `schedules list` / `set` / `rm` | running functions on a timer (timer triggers) |
 | `env` / `env check` / `env set` | environment variables of the functions, values are never handed back |
+| `connections` / `connections link` / `connections unlink` | connected accounts the functions can use, and their variables |
 | `logs` | browser errors from the released application |
-| `projects list` / `projects get` / `open` | projects of the organization and the application addresses |
+| `projects list` / `projects get` | projects of the organization and the application addresses |
 | `skills` | platform instructions for an AI agent ([Agent Skills](https://agentskills.io) format) |
 | `mcp install` | connect the agent to the platform directly, without a terminal |
 | `update` | update the CLI itself, and the skill that ships inside it |

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

@@ -21,6 +21,14 @@ const SCOPE_LABEL = {
 const FUNCTIONS_DIR = 'functions';
 /** Matches `process.env.NAME` and `process.env['NAME']`. */
 const ENV_REFERENCE = /process\.env(?:\.([A-Z0-9_]+)|\[['"]([A-Z0-9_]+)['"]\])/g;
+/**
+ * Reading the environment in a shape no name can be read from: a name built from
+ * an expression, reached through `?.`, destructured or spread. The platform
+ * passes a variable only to a function that spells its name out, so these reads
+ * arrive empty and the build gate rejects them. The same rule lives on the
+ * platform side in lib/env-references.ts and the two must agree.
+ */
+const OPAQUE_REFERENCE = /process\.env\b(?!\.[A-Z0-9_]+|\[['"][A-Z0-9_]+['"]\])/;
 /** Set by the platform itself. */
 const PROVIDED = new Set([
     'XFLOW_PROJECT_ID',
@@ -28,6 +36,7 @@ const PROVIDED = new Set([
     'XFLOW_PROJECT_SCHEMA',
     'XFLOW_FUNCTION_NAME',
     'XFLOW_API_URL',
+    'XFLOW_SERVER_KEY',
     'DATABASE_URL',
     'NODE_ENV',
 ]);
@@ -47,8 +56,11 @@ function sourceFiles(dir, found = []) {
 function referencedByFunctions(root) {
     const needed = new Map();
     const provided = new Map();
-    for (const file of sourceFiles((0, node_path_1.join)(root, FUNCTIONS_DIR))) {
-        const functionName = file.slice((0, node_path_1.join)(root, FUNCTIONS_DIR).length + 1).split(/[\\/]/)[0];
+    const opaque = new Map();
+    const base = (0, node_path_1.join)(root, FUNCTIONS_DIR);
+    for (const file of sourceFiles(base)) {
+        const relative = file.slice(base.length + 1);
+        const functionName = relative.split(/[\\/]/)[0];
         const code = (0, node_fs_1.readFileSync)(file, 'utf-8');
         for (const match of code.matchAll(ENV_REFERENCE)) {
             const name = match[1] || match[2];
@@ -60,8 +72,15 @@ function referencedByFunctions(root) {
                 users.push(functionName);
             target.set(name, users);
         }
+        code.split('\n').forEach((line, index) => {
+            if (!OPAQUE_REFERENCE.test(line))
+                return;
+            const places = opaque.get(functionName) ?? [];
+            places.push(`${FUNCTIONS_DIR}/${relative.replace(/\\/g, '/')}:${index + 1}`);
+            opaque.set(functionName, places);
+        });
     }
-    return { needed, provided };
+    return { needed, provided, opaque };
 }
 async function fetchVariables() {
     const { root, config } = (0, config_1.requireProject)();
@@ -82,8 +101,8 @@ async function envList() {
 /** Check that every referenced variable is stored. */
 async function envCheck() {
     const { names, root } = await fetchVariables();
-    const { needed, provided } = referencedByFunctions(root);
-    if (needed.size === 0 && provided.size === 0) {
+    const { needed, provided, opaque } = referencedByFunctions(root);
+    if (needed.size === 0 && provided.size === 0 && opaque.size === 0) {
         (0, ui_1.note)('The functions of this project read no environment variables');
         return;
     }
@@ -106,14 +125,33 @@ async function envCheck() {
         (0, ui_1.out)((0, ui_1.bold)('Stored on the platform:'));
         (0, ui_1.table)(present);
     }
-    if (missing.length === 0) {
+    if (missing.length > 0) {
+        (0, ui_1.out)('');
+        (0, ui_1.fail)('Missing on the platform:');
+        (0, ui_1.table)(missing);
+    }
+    if (opaque.size > 0) {
+        (0, ui_1.out)('');
+        (0, ui_1.fail)('Reading the environment without naming the variable:');
+        (0, ui_1.table)([...opaque.entries()].sort().map(([name, places]) => [name, places.join(', ')]));
+        (0, ui_1.note)((0, ui_1.dim)('  A name built from an expression, reached through ?., destructured or spread is invisible to the platform: ' +
+            'the value never arrives and the build is rejected'));
+    }
+    if (missing.length === 0 && opaque.size === 0) {
         (0, ui_1.ok)('Every function has the variables it needs');
         return;
     }
-    (0, ui_1.out)('');
-    (0, ui_1.fail)('Missing on the platform:');
-    (0, ui_1.table)(missing);
-    throw new errors_1.CliError(`Missing variables: ${missing.length}`, 'To store them: xflow env set NAME=value. Until then the function receives undefined');
+    const problems = [];
+    const hints = [];
+    if (missing.length > 0) {
+        problems.push(`missing variables: ${missing.length}`);
+        hints.push('To store one: xflow env set NAME=value. Until then the function receives undefined');
+    }
+    if (opaque.size > 0) {
+        problems.push(`functions reading the environment without naming it: ${opaque.size}`);
+        hints.push('Spell every variable name out: process.env.NAME');
+    }
+    throw new errors_1.CliError(problems.join(', '), hints.join('. '));
 }
 async function envSet(args) {
     const { root, config } = (0, config_1.requireProject)();

package/dist/commands/projects.js

@@ -13,6 +13,7 @@ const config_1 = require("../config");
 const errors_1 = require("../errors");
 const session_1 = require("../session");
 const skills_1 = require("./skills");
+const sources_1 = require("./sources");
 const template_1 = require("../template");
 const zip_1 = require("../zip");
 const ui_1 = require("../ui");
@@ -102,6 +103,9 @@ async function init(args) {
 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;
+    // Asked before anything is written: an empty folder means a clone, and the
+    // sources have to come with it.
+    const fresh = !existing && isEmptyEnough(process.cwd());
     let client = (0, session_1.connect)(existing);
     const projectId = args.words[0];
     if (!projectId) {
@@ -147,6 +151,24 @@ async function link(args) {
     (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)
+        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.
+    try {
+        const { info, files } = await (0, sources_1.downloadRevision)(client, card.id, dir);
+        (0, config_1.writeState)(dir, { revision: info.revision, treeHash: info.tree_hash });
+        (0, ui_1.ok)(`Revision ${info.revision}: ${files} files`);
+    }
+    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'));
+            return;
+        }
+        (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'));
+    }
 }
 async function list() {
     const root = (0, config_1.findProjectRoot)();

package/dist/commands/sources.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.latestRevision = latestRevision;
 exports.pushSources = pushSources;
+exports.downloadRevision = downloadRevision;
 exports.pull = pull;
 exports.status = status;
 const node_fs_1 = require("node:fs");
@@ -14,8 +15,8 @@ const session_1 = require("../session");
 const tree_1 = require("../tree");
 const zip_1 = require("../zip");
 const ui_1 = require("../ui");
-/** Server cap, checked locally to fail before uploading. */
-const MAX_ARCHIVE_BYTES = 25 * 1024 * 1024;
+/** Server cap, checked locally to fail before uploading. Keep in sync with the server. */
+const MAX_ARCHIVE_BYTES = 10 * 1024 * 1024;
 function prepareTree(root, config) {
     const buildDir = config.build?.dir?.replace(/^\.\//, '').replace(/\/+$/, '');
     const extra = [...(config.ignore ?? []), ...(buildDir ? [`${buildDir}/`] : [])];
@@ -31,7 +32,8 @@ function prepareTree(root, config) {
         const top = (0, tree_1.heaviest)(files)
             .map((f) => `    ${f.path}  ${(0, ui_1.formatBytes)(f.content.length)}`)
             .join('\n');
-        throw new errors_1.CliError(`The archive is ${(0, ui_1.formatBytes)(archive.length)}, the cap is ${(0, ui_1.formatBytes)(MAX_ARCHIVE_BYTES)}`, `The heaviest files:\n${top}\n  Exclude what is not needed in .xflowignore`);
+        throw new errors_1.CliError(`The archive is ${(0, ui_1.formatBytes)(archive.length)}, the cap is ${(0, ui_1.formatBytes)(MAX_ARCHIVE_BYTES)}`, `The heaviest files:\n${top}\n  Exclude what is not needed in .xflowignore.\n` +
+            '  Heavy media the app loads at runtime belong in the project file storage, not in the build');
     }
     return { files, hash: (0, tree_1.treeHash)(files), archive };
 }
@@ -64,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');
 }
@@ -110,23 +112,29 @@ async function pushSources(root, config, client, options) {
     }
     return { revision: result.revision, status: result.status };
 }
+/**
+ * Does the folder hold work of its own?
+ *
+ * Only sources count. What `xflow link` itself lays down (xflow.json, the agent
+ * instructions, dot-files the platform or the editor keeps) is bookkeeping, and
+ * counting it turned the documented way to clone a project into a dead end:
+ * link wrote its files, and the pull that follows refused over them.
+ */
 function hasContent(dir) {
     if (!(0, node_fs_1.existsSync)(dir))
         return false;
-    return (0, node_fs_1.readdirSync)(dir).some((name) => name !== '.git' && name !== '.xflow');
+    return (0, node_fs_1.readdirSync)(dir).some((name) => !name.startsWith('.') && name !== config_1.CONFIG_FILE && name !== 'AGENTS.md');
 }
-async function pull(args) {
-    const { root, config } = (0, config_1.requireProject)();
-    const into = (0, args_1.flagString)(args, 'into');
-    const target = into ? (0, node_path_1.resolve)(into) : root;
-    const client = await (0, session_1.connectProject)(root, config);
-    const revision = (0, args_1.flagNumber)(args, 'revision');
+/**
+ * Write a server revision into `target`.
+ *
+ * Shared with `xflow link`: linking an empty folder and then being told the
+ * folder is not empty for a pull is a dead end the platform can avoid by
+ * fetching the sources itself.
+ */
+async function downloadRevision(client, projectId, target, revision) {
     const query = revision !== undefined ? `?revision=${revision}` : '';
-    const info = await (0, api_1.apiJson)(client, `/api/v1/projects/${config.projectId}/pull${query}`);
-    if (hasContent(target) && !(0, args_1.flagBool)(args, 'force')) {
-        throw new errors_1.CliError(`The directory ${target} is not empty`, 'The platform cannot merge changes, that is git work. Fetch the server copy alongside: ' +
-            'xflow pull --into ./server-copy, or overwrite the folder completely: xflow pull --force');
-    }
+    const info = await (0, api_1.apiJson)(client, `/api/v1/projects/${projectId}/pull${query}`);
     (0, ui_1.step)(`Downloading revision ${info.revision} (${(0, ui_1.formatBytes)(info.size_bytes)})`);
     const entries = (0, zip_1.zipRead)(await (0, api_1.downloadUrl)(info.download_url));
     const hash = (0, tree_1.treeHash)(entries.map((e) => ({ path: e.path, content: e.content })));
@@ -134,11 +142,24 @@ async function pull(args) {
         (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 });
-    for (const entry of (0, zip_1.dropDirectoryEntries)(entries)) {
+    const files = (0, zip_1.dropDirectoryEntries)(entries);
+    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 });
         (0, node_fs_1.writeFileSync)(path, entry.content);
     }
+    return { info, files: files.length };
+}
+async function pull(args) {
+    const { root, config } = (0, config_1.requireProject)();
+    const into = (0, args_1.flagString)(args, 'into');
+    const target = into ? (0, node_path_1.resolve)(into) : root;
+    const client = await (0, session_1.connectProject)(root, config);
+    if (hasContent(target) && !(0, args_1.flagBool)(args, 'force')) {
+        throw new errors_1.CliError(`The directory ${target} is not empty`, 'The platform cannot merge changes, that is git work. Fetch the server copy alongside: ' +
+            'xflow pull --into ./server-copy, or overwrite the folder completely: xflow pull --force');
+    }
+    const { info, files } = await downloadRevision(client, config.projectId, target, (0, args_1.flagNumber)(args, 'revision'));
     // Only the working folder tracks revisions; a side copy (--into) must not reset them.
     if (!into) {
         (0, config_1.writeState)(root, {
@@ -147,16 +168,19 @@ async function pull(args) {
             organizationId: client.organizationId ?? undefined,
         });
     }
-    (0, ui_1.ok)(`Revision ${info.revision}: ${entries.length} files in ${target}`);
+    (0, ui_1.ok)(`Revision ${info.revision}: ${files} files in ${target}`);
 }
 async function status() {
     const { root, config } = (0, config_1.requireProject)();
     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)('');
@@ -179,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

@@ -15,7 +15,7 @@ ${(0, ui_1.bold)('Getting started')}
   xflow login                     sign in through the browser
   xflow init [dir]                new project from the platform template
   xflow templates                 which templates are available
-  xflow link <id>                 link this folder to a project (id: xflow projects list)
+  xflow link <id>                 link this folder to a project, an empty one also gets the sources
   xflow skills                    pick the agents that get the platform instructions
   xflow mcp install               give the agent platform access without a terminal
 
@@ -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')}
@@ -194,8 +194,10 @@ the function. So keep your own copy wherever you got it from.
 
 ${(0, ui_1.bold)('check')} reads the sources in ${(0, ui_1.bold)('functions/')} and looks for ${(0, ui_1.bold)('process.env.NAME')}
 references. The same rule applies on deploy: a function receives only the variables it
-mentions by name. A name assembled from an expression (${(0, ui_1.bold)("process.env['KEY_' + n]")})
-never reaches the environment, so read variables literally.
+mentions by name. A name assembled from an expression (${(0, ui_1.bold)("process.env['KEY_' + n]")}),
+reached through ${(0, ui_1.bold)('?.')}, destructured or spread never reaches the environment, so read
+variables literally. ${(0, ui_1.bold)('check')} names those reads and the build rejects them: a secret
+that quietly fails to arrive is found by the function falling over weeks later.
 
 The value reaches the function on deploy, not at the moment it is stored: after
 ${(0, ui_1.bold)('env set')} run ${(0, ui_1.bold)('xflow deploy')}. The build ships a function whose code did not
@@ -394,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.8.1';
+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.8.1",
+  "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

@@ -27,8 +27,9 @@ These mistakes cost the most because nothing fails at the moment they are made,
 the error points away from the cause. The sections below carry the details.
 
 1. Read environment variables literally: `process.env.API_KEY`. Destructuring
-   (`const { API_KEY } = process.env`) reads as no mention of the variable at all,
-   and it arrives empty.
+   (`const { API_KEY } = process.env`), a name built from an expression, `?.` and
+   spreading the environment all read as no mention of the variable at all. The
+   build rejects them, and `xflow env check` names them before that.
 2. A value written with `xflow env set` reaches the functions on the next
    `xflow deploy`, not at the moment it is written.
 3. Never delete a `functions/<name>/` directory unless the user asked for that
@@ -72,12 +73,29 @@ 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
+backup of the code: the code lives in revisions (the last 100, and a revision a live
+version was built from is never deleted), and a build is made from a revision again.
+Keep anything you must not lose in your own git repository, not in the version history.
 
 **The only link you give a person is the project page**, `https://app.getxflow.com/projects/<id>`,
 which the CLI prints for you. Refer to builds by their number ("version 481203 is built,
@@ -247,9 +265,11 @@ functions read but the platform does not have. Values never come back out — th
 they exist is inside the running function.
 
 A function receives only the variables it mentions by name via `process.env.NAME`, so never
-assemble a variable name from an expression and never destructure the environment
-(`const { API_KEY } = process.env` reads as no mention at all, and the variable arrives
-empty). New values arrive on the next `xflow deploy`, not at the moment they are written.
+assemble a variable name from an expression, never reach the environment through `?.`, and
+never destructure or spread it (`const { API_KEY } = process.env` reads as no mention at all,
+and the variable arrives empty). The build stops on such a read rather than shipping a
+function whose secret silently never arrives. New values arrive on the next `xflow deploy`,
+not at the moment they are written.
 
 Some variables come from a connected account instead of from you. When someone connects an
 advertising cabinet or another external service in the platform settings and links it to the
@@ -341,6 +361,12 @@ a migration against a shared database.
 
 ## File storage
 
+Sources go up as one archive, capped at 10 MB. That cap is about heavy media, not about
+code: an app with hundreds of files is nowhere near it. Icons, fonts and small artwork the
+build needs belong in the repository as usual. Photos, video, PDFs and anything a user
+uploads belong in file storage, which is metered against the organization plan and is not
+rebuilt and re-uploaded on every deploy.
+
 The project has file storage, and the browser cannot reach it. Those endpoints take only the
 server key of the project, and the platform puts it into the environment of your cloud
 functions as `XFLOW_SERVER_KEY`. Nothing else holds it: not the bundle, not `.env`, not

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\./);
-});