@getxflow/cli 0.1.10 → 0.2.0

package/README.md

@@ -21,7 +21,7 @@ else's code belongs next to it.
 | `status` / `push` / `pull` | state, sending and fetching sources |
 | `deploy` / `publish` / `rollback` / `deployments` | build, publish, roll back, version history |
 | `db status` / `db migrate` | migrations from `migrations/*.sql` with a gate on destructive ones |
-| `functions list` / `functions deploy` | cloud functions of the project from `functions/<name>/index.ts` |
+| `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 |

package/dist/bin.js

@@ -69,9 +69,9 @@ async function run(args) {
             }
             throw new errors_1.CliError(`Unknown command: mcp ${second}`, 'Available: install');
         case 'functions':
+            // The command is gone, but silence would leave the habit unexplained.
             if (second === 'deploy') {
-                await (0, functions_1.functionsDeploy)(rest);
-                return;
+                throw new errors_1.CliError('Functions are deployed by the build now', 'Run xflow deploy: it ships the functions and then builds the application with their addresses');
             }
             if (second === 'invoke') {
                 await (0, functions_1.functionsInvoke)(rest);
@@ -85,7 +85,7 @@ async function run(args) {
                 await (0, functions_1.functionsList)();
                 return;
             }
-            throw new errors_1.CliError(`Unknown command: functions ${second}`, 'Available: list, deploy, invoke and logs');
+            throw new errors_1.CliError(`Unknown command: functions ${second}`, 'Available: list, invoke and logs');
         case 'logs':
             await (0, logs_1.logs)(rest);
             return;

package/dist/commands/deploy.js

@@ -4,11 +4,14 @@ exports.deploy = deploy;
 exports.publish = publish;
 exports.rollback = rollback;
 exports.deployments = deployments;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
 const api_1 = require("../api");
 const args_1 = require("../args");
 const config_1 = require("../config");
 const errors_1 = require("../errors");
 const session_1 = require("../session");
+const template_1 = require("../template");
 const ui_1 = require("../ui");
 const sources_1 = require("./sources");
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
@@ -40,6 +43,24 @@ async function waitForBuild(client, projectId, started) {
     }
     throw new errors_1.CliError('The build is taking longer than expected', `To check the state: xflow deployments. Version ${started.deploy_id}`);
 }
+/**
+ * Write the function addresses into the local .env.
+ *
+ * The build bakes its own copy of the map into the bundle, this one is for
+ * `npm run dev`: without it the local run calls a function that it has no
+ * address for.
+ */
+async function refreshFunctionsEnv(root, client, projectId) {
+    const card = await (0, api_1.apiJson)(client, `/api/v1/projects/${projectId}`);
+    // No .env at all (fresh clone): recreate it fully, like link does.
+    if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(root, '.env')) && card.project_token) {
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(root, '.env'), (0, template_1.envFile)(card.project_token, client.apiUrl, card.functions), 'utf-8');
+    }
+    else {
+        (0, template_1.writeEnvValue)(root, template_1.FUNCTIONS_ENV_KEY, (0, template_1.functionsEnvValue)(card.functions));
+    }
+    return card.functions.filter((fn) => fn.invoke_url).map((fn) => fn.name);
+}
 async function deploy(args) {
     const { root, config } = (0, config_1.requireProject)();
     const client = (0, session_1.connect)(config);
@@ -68,6 +89,11 @@ async function deploy(args) {
             reportIssues(e);
         throw e;
     }
+    // Removing a function cannot be undone: a new one gets a new address. Say it
+    // out loud rather than leaving it to be discovered in functions list.
+    if (started.removed_functions?.length) {
+        (0, ui_1.warn)(`Removed from the cloud, gone from the sources: ${started.removed_functions.join(', ')}`);
+    }
     const build = await waitForBuild(client, config.projectId, started);
     if (build.phase === 'failed') {
         if (build.log_tail) {
@@ -78,6 +104,17 @@ async function deploy(args) {
     }
     (0, ui_1.ok)(`Version ${build.deploy_id} built from revision ${build.revision} in ${build.elapsed_s} s`);
     (0, ui_1.out)(build.project_url);
+    // The functions were shipped by the build itself, so their addresses are known
+    // only now. A failure here does not undo a finished build: warn and stop there.
+    try {
+        const functions = await refreshFunctionsEnv(root, client, config.projectId);
+        if (functions.length > 0) {
+            (0, ui_1.note)((0, ui_1.dim)(`  Functions in .env: ${functions.join(', ')}`));
+        }
+    }
+    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'));
 }
 async function publish() {

package/dist/commands/env.js

@@ -126,7 +126,7 @@ async function envSet(args) {
     // Values reach a function on its next deploy.
     const users = referencedByFunctions(root).needed.get(name);
     if (users && users.length > 0) {
-        (0, ui_1.note)((0, ui_1.dim)(`  For the value to arrive, redeploy: xflow functions deploy ${users.join(' && xflow functions deploy ')}`));
+        (0, ui_1.note)((0, ui_1.dim)(`  For the value to arrive, run xflow deploy: it ships ${users.join(', ')} again`));
     }
 }
 async function envRemove(args) {

package/dist/commands/functions.js

@@ -2,68 +2,19 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.functionsList = functionsList;
 exports.functionsInvoke = functionsInvoke;
-exports.functionsDeploy = functionsDeploy;
-const node_fs_1 = require("node:fs");
-const node_path_1 = require("node:path");
 const api_1 = require("../api");
 const args_1 = require("../args");
 const config_1 = require("../config");
 const errors_1 = require("../errors");
 const session_1 = require("../session");
-const template_1 = require("../template");
 const ui_1 = require("../ui");
-const ENTRY_NAMES = ['index.ts', 'index.js', 'index.mjs'];
 const FUNCTIONS_DIR = 'functions';
-function entryFor(root, name) {
-    for (const entry of ENTRY_NAMES) {
-        const candidate = (0, node_path_1.join)(root, FUNCTIONS_DIR, name, entry);
-        if ((0, node_fs_1.existsSync)(candidate))
-            return candidate;
-    }
-    return null;
-}
-function discover(root) {
-    const dir = (0, node_path_1.join)(root, FUNCTIONS_DIR);
-    if (!(0, node_fs_1.existsSync)(dir))
-        return [];
-    return (0, node_fs_1.readdirSync)(dir)
-        .filter((name) => (0, node_fs_1.statSync)((0, node_path_1.join)(dir, name)).isDirectory())
-        .filter((name) => entryFor(root, name) !== null)
-        .sort();
-}
-/**
- * Bundle a function into one file. esbuild comes from the project's node_modules;
- * `pg` stays external so the server wrapper can inject the project schema.
- */
-function bundle(root, entry) {
-    let esbuild;
-    try {
-        esbuild = require(require.resolve('esbuild', { paths: [root] }));
-    }
-    catch {
-        throw new errors_1.CliError('Could not find esbuild in the project', 'Install it: npm i -D esbuild. It usually comes with Vite already');
-    }
-    const result = esbuild.buildSync({
-        entryPoints: [entry],
-        bundle: true,
-        platform: 'node',
-        target: 'node20',
-        format: 'cjs',
-        external: ['pg'],
-        write: false,
-        logLevel: 'silent',
-    });
-    const text = result.outputFiles[0]?.text;
-    if (!text)
-        throw new errors_1.CliError(`Building ${entry} produced nothing`);
-    return text;
-}
 async function functionsList() {
     const { config } = (0, config_1.requireProject)();
     const client = (0, session_1.connect)(config);
     const data = await (0, api_1.apiJson)(client, `/api/v1/projects/${config.projectId}/functions`);
     if (data.functions.length === 0) {
-        (0, ui_1.note)(`No functions. Put the code in ${FUNCTIONS_DIR}/<name>/index.ts and run xflow functions deploy`);
+        (0, ui_1.note)(`No functions. Put the code in ${FUNCTIONS_DIR}/<name>/index.ts and run xflow deploy`);
         return;
     }
     (0, ui_1.table)(data.functions.map((fn) => [
@@ -73,18 +24,6 @@ async function functionsList() {
         fn.error_message ?? '',
     ]));
 }
-/** Write function URLs into .env, where the build picks them up. */
-async function refreshFunctionsEnv(root, client, projectId) {
-    const card = await (0, api_1.apiJson)(client, `/api/v1/projects/${projectId}`);
-    // No .env at all (fresh clone): recreate it fully, like link does.
-    if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(root, '.env')) && card.project_token) {
-        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(root, '.env'), (0, template_1.envFile)(card.project_token, client.apiUrl, card.functions), 'utf-8');
-    }
-    else {
-        (0, template_1.writeEnvValue)(root, template_1.FUNCTIONS_ENV_KEY, (0, template_1.functionsEnvValue)(card.functions));
-    }
-    return card.functions.filter((fn) => fn.invoke_url).map((fn) => fn.name);
-}
 function prettyBody(text) {
     try {
         return JSON.stringify(JSON.parse(text), null, 2);
@@ -105,7 +44,7 @@ async function functionsInvoke(args) {
     if (!fn || !fn.invoke_url) {
         throw new errors_1.CliError(`Function ${name} is not deployed`, card.functions.length > 0
             ? `Deployed: ${card.functions.map((item) => item.name).join(', ')}`
-            : `To deploy it: xflow functions deploy ${name}`);
+            : 'Functions ship with the build: xflow deploy');
     }
     const data = (0, args_1.flagString)(args, 'data');
     const method = ((0, args_1.flagString)(args, 'method') ?? (data ? 'POST' : 'GET')).toUpperCase();
@@ -136,29 +75,3 @@ async function functionsInvoke(args) {
         throw new errors_1.CliError(`The function answered ${response.status}`, `The stack and console output: xflow functions logs ${name}`);
     }
 }
-async function functionsDeploy(args) {
-    const { root, config } = (0, config_1.requireProject)();
-    const client = (0, session_1.connect)(config);
-    const wanted = args.words[1];
-    const names = wanted ? [wanted] : discover(root);
-    if (names.length === 0) {
-        throw new errors_1.CliError(`The project has no functions`, `Create ${FUNCTIONS_DIR}/<name>/index.ts exporting handler and try again`);
-    }
-    for (const name of names) {
-        const entry = entryFor(root, name);
-        if (!entry) {
-            throw new errors_1.CliError(`Could not find ${FUNCTIONS_DIR}/${name}/index.ts`, `Available functions: ${discover(root).join(', ') || 'none at all'}`);
-        }
-        (0, ui_1.step)(`Building ${name}`);
-        const code = bundle(root, entry);
-        (0, ui_1.step)(`Deploying ${name}`);
-        const result = await (0, api_1.apiUpload)(client, `/api/v1/projects/${config.projectId}/functions?name=${encodeURIComponent(name)}`, Buffer.from(code, 'utf-8'), { 'Content-Type': 'application/javascript' });
-        (0, ui_1.ok)(`${(0, ui_1.bold)(result.name)} deployed`);
-        (0, ui_1.out)(result.url);
-        if (result.secrets.length > 0) {
-            (0, ui_1.note)((0, ui_1.dim)(`  Organization secrets in the environment: ${result.secrets.join(', ')}`));
-        }
-    }
-    const available = await refreshFunctionsEnv(root, client, config.projectId);
-    (0, ui_1.note)((0, ui_1.dim)(`  Addresses in .env updated (${available.join(', ')}). In the frontend: xflow.functions.invoke('${names[0]}')`));
-}

package/dist/help.js

@@ -26,14 +26,13 @@ ${(0, ui_1.bold)('Code')}
                                   fetch the sources (the latest revision by default)
 
 ${(0, ui_1.bold)('Releasing')}
-  xflow deploy [--no-push]        send the code, build on the platform, release to dev
+  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 deployments               version history
 
 ${(0, ui_1.bold)('Functions')}
-  xflow functions list            what is deployed
-  xflow functions deploy [name]   build and ship a function
+  xflow functions list            what is deployed (they ship with xflow deploy)
   xflow functions invoke <name> [--data '{"a":1}']
                                   call a function and print the answer
   xflow functions logs [name]     function crashes: stack and console output
@@ -125,8 +124,9 @@ mentions by name. A name assembled from an expression (${(0, ui_1.bold)("process
 never reaches the environment, so read variables literally.
 
 The value reaches the function on deploy, not at the moment it is stored: after
-${(0, ui_1.bold)('env set')} you need ${(0, ui_1.bold)('xflow functions deploy')} for the functions involved. The same
-after a delete: a function already deployed keeps the old value until its next deploy.`,
+${(0, ui_1.bold)('env set')} run ${(0, ui_1.bold)('xflow deploy')}. The build ships a function whose code did not
+change but whose variables did, so nothing is left holding an old value. The same after a
+delete: a function already deployed keeps the old value until its next deploy.`,
     schedules: `${(0, ui_1.bold)('xflow schedules')}: running functions on a timer
 
 A schedule is a Yandex timer trigger: it calls the function itself, with no
@@ -224,8 +224,9 @@ into a non-empty one: the platform cannot merge changes, that is git's job.
   --force            overwrite the folder completely`,
     deploy: `${(0, ui_1.bold)('xflow deploy')}: build and release
 
-Two steps: sending the sources and building on the platform. The build command and the
-output directory come from xflow.json (npm run build and dist by default).
+Three steps: sending the sources, shipping the cloud functions, building the application.
+The build command and the output directory come from xflow.json (npm run build and dist
+by default).
 
   --no-push       do not send sources, build from the latest server revision
   --force         allow overwriting the server revision while sending
@@ -235,6 +236,21 @@ worked on my machine" no longer depends on your machine. Before the build the pr
 is checked against the template: mismatches are printed as a list and the build does
 not start at all.
 
+Everything in ${(0, ui_1.bold)('functions/<name>/index.ts')} is bundled and shipped by the same run,
+before the application is built. That order is not a convention but the only one that
+works: the addresses of the functions are baked into the bundle, so they have to exist
+first. A function whose code and variables did not change is left alone, and a function
+that fails to ship fails the whole build.
+
+A function gone from the sources is deleted from the cloud along with its schedules, and
+the CLI names it before the build starts. That one is final: a function created again
+later gets a different address. If the sources hold no functions at all while the cloud
+holds several, nothing is deleted: that looks like a directory which never made it (a
+${(0, ui_1.bold)('functions/')} line in .xflowignore) rather than a decision.
+
+The database is not part of this: migrations change data in ways nothing can undo, so
+they stay their own command (${(0, ui_1.bold)('xflow db migrate')}).
+
 The built version is visible on the project page, and the CLI prints the link. Visitors
 see it after ${(0, ui_1.bold)('xflow publish')}. The address of the build itself is not printed:
 it carries the version number, and after the next publish such a link quietly serves an

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

package/skills/xflow/SKILL.md

@@ -40,8 +40,8 @@ restored within an hour of the data going back under the limit.
 2. `npm run typecheck` for a two-second type check (older projects may not have the
    script, then `npx tsc --noEmit`).
 3. `npm run build` if the change is substantial, before deploying.
-4. `xflow deploy` sends the sources and builds them on the platform, printing each
-   phase and the six-digit number of the version it built.
+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.
 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.
@@ -105,11 +105,16 @@ Interface rules, checked outside `src/components/ui` and `src/components/blocks`
 
 ## Cloud functions
 
-Server-side code lives in `functions/<name>/index.ts` and exports `handler`. Deploy it
-with `xflow functions deploy` (one name to deploy a single function, no name for all),
-list what is live with `xflow functions list`. The handler returns
+Server-side code lives in `functions/<name>/index.ts` and exports `handler`. There is no
+separate deploy command: `xflow deploy` ships the functions and then builds the application,
+in that order. List what is live with `xflow functions list`. The handler returns
 `{ statusCode, body }` where `body` is a JSON string.
 
+The sources are the whole truth about which functions exist. Delete the directory and the
+next deploy deletes 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
+directory to "clean up" unless the user asked for the function to go.
+
 Debugging a deployed function is two commands: `xflow functions invoke <name>` calls it
 the way the app does and prints status, timing and body (`--data '{"a":1}'` sends a body),
 and `xflow functions logs <name>` shows the failures, each with its stack and the console
@@ -118,9 +123,9 @@ never crashed, not that logging is broken.
 
 From the app, call a function through `src/lib/xflow.ts`:
 `await xflow.functions.invoke('send-mail', { body: { to } })`. It carries the project
-token for you. Addresses are baked into the build: the CLI writes them to `.env` when
-you deploy a function, so a frontend built before the function existed cannot see it,
-and needs `xflow deploy` again.
+token for you. Addresses are baked into the build, which is why the functions go out first:
+by the time the bundle is built they already exist, and a new function is never missing
+from the application that calls it.
 
 Treat a function as a public API: the token ships inside the frontend bundle, so anyone
 who opens the app can call it.
@@ -131,8 +136,8 @@ 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. New values arrive on the next
-`xflow functions deploy`, not at the moment they are written.
+assemble a variable name from an expression. New values arrive on the next `xflow deploy`,
+not at the moment they are written.
 
 To run a function on a timer: `xflow schedules set report "0 3 ? * * *"` (daily at 03:00).
 Six fields, UTC, and exactly one of day-of-month / day-of-week must be `?` — that is
@@ -184,12 +189,12 @@ read-only queries, migrations, function logs and invocations, schedules, environ
 variables, versions, publish and rollback. They answer with aggregates and say explicitly
 when a result is truncated, which parsing terminal output does not.
 
-Code never travels through those tools. Sending sources and deploying functions stay in
-the CLI (`xflow push`, `xflow functions deploy`): pulling a repository through tool calls
-burns the user's tokens for nothing. Building is available through the tools, because it
-runs from the revision already stored on the server: `deployments action=build` starts it
-and answers immediately, `action=status` reports the phase. A build takes minutes, so
-never expect the starting call to return a finished version.
+Code never travels through those tools. Sending sources stays in the CLI (`xflow push`):
+pulling a repository through tool calls burns the user's tokens for nothing. Building is
+available through the tools, because it runs from the revision already stored on the
+server: `deployments action=build` starts it and answers immediately, `action=status`
+reports the phase. It ships the functions too, from that same revision. A build takes
+minutes, so never expect the starting call to return a finished version.
 
 ## Do not