@getxflow/cli 0.8.1 → 0.9.0

package/README.md

@@ -17,7 +17,8 @@ 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 |
 | `db status` / `db migrate` | migrations from `migrations/*.sql` with a gate on destructive ones |
@@ -26,8 +27,9 @@ else's code belongs next to it.
 | `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/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 };
 }
@@ -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,7 +168,7 @@ 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)();

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
 
@@ -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

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.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.8.1",
+  "version": "0.9.0",
   "description": "CLI for the XFlow platform: source sync, deployment and publishing of applications",
   "license": "UNLICENSED",
   "engines": {

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
@@ -79,6 +80,12 @@ 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.
 
+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,
 092399 is what visitors see"), never by address. The platform does not hand out build
@@ -247,9 +254,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 +350,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