@getxflow/cli 0.29.0 → 0.30.0

package/dist/args.js

@@ -8,6 +8,7 @@ exports.flagBool = flagBool;
 exports.flagNumber = flagNumber;
 /** Flags that never take a value, so `--force ./dir` keeps the path as a word. */
 exports.BOOLEAN_FLAGS = new Set([
+    'function',
     'force',
     'yes',
     'json',

package/dist/commands/db.js

@@ -143,7 +143,6 @@ function serverRow(server) {
         server.status === 'active' ? '' : server.status,
         room,
         `${server.databases} ${server.databases === 1 ? 'database' : 'databases'}`,
-        server.new_databases_here ? 'new databases go here' : '',
     ];
 }
 function attachedProjects(database) {
@@ -207,7 +206,7 @@ function printServers(servers) {
     (0, ui_1.out)('');
     (0, ui_1.out)((0, ui_1.bold)('Servers'));
     (0, ui_1.table)(servers.map(serverRow));
-    (0, ui_1.note)((0, ui_1.dim)('  A new project with its database on one of them: xflow init --server <name>. An existing one: xflow db move --to <name>'));
+    (0, ui_1.note)((0, ui_1.dim)('  Without --server a new database goes to the platform server. To put it on another: xflow init --server <name>, or xflow db move --to <name> for one that already exists'));
 }
 /** Long values would tear the columns apart; the cut is marked, never silent. */
 const CELL_LIMIT = 60;

package/dist/commands/deploy.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.versionComment = versionComment;
+exports.statedRevision = statedRevision;
 exports.deploy = deploy;
 exports.publish = publish;
 exports.rollback = rollback;
@@ -56,7 +57,7 @@ async function waitForBuild(client, projectId, started) {
  */
 async function refreshPlatformEnv(root, client, projectId) {
     const card = await (0, api_1.apiJson)(client, `/api/v1/projects/${projectId}`);
-    (0, template_1.writePlatformEnv)(root, card.project_token, client.apiUrl, card.functions);
+    (0, template_1.writePlatformEnv)(root, card.project_token, client.apiUrl, card.functions, card.function_map);
     return card.functions.filter((fn) => fn.invoke_url).map((fn) => fn.name);
 }
 /**
@@ -141,25 +142,14 @@ function requireComment(args) {
     }
     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;
-    if ((0, args_1.flagBool)(args, 'no-push')) {
-        const server = await (0, sources_1.latestRevision)(client, config.projectId);
-        if (!server) {
-            throw new errors_1.CliError('The server holds no sources', 'Repeat without --no-push, so that the sources go up first');
-        }
-        revision = server.revision;
-        (0, ui_1.warn)(`Sources not sent (--no-push), the build runs from revision ${revision}`);
-    }
-    else {
-        await assertBuildAllowed(client, config.projectId);
-        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'), comment);
+/**
+ * Everything after the build has started: the same for a build of the sources
+ * just sent and for a rebuild of a revision the platform already holds.
+ *
+ * `root` is the folder to point at this project afterwards, and null when there
+ * is none: a build asked for by id has no .env to refresh.
+ */
+async function finishBuild(client, projectId, started, root) {
     if (started.removed_functions?.length) {
         (0, ui_1.warn)(`Removed from the cloud, gone from the sources: ${started.removed_functions.join(', ')}`);
     }
@@ -167,7 +157,11 @@ async function deploy(args) {
         (0, ui_1.warn)(`Access revoked by the provider: ${started.revoked_connections.join(', ')}`);
         (0, ui_1.note)((0, ui_1.dim)('  Reconnect the account in the platform settings: another build will not fix this'));
     }
-    const build = await waitForBuild(client, config.projectId, started);
+    if (started.shadowed_functions?.length) {
+        (0, ui_1.warn)(`Named like a standalone function of the organization: ${started.shadowed_functions.join(', ')}`);
+        (0, ui_1.note)((0, ui_1.dim)('  The app calls its own function under that name. Rename one of them to call the shared one'));
+    }
+    const build = await waitForBuild(client, projectId, started);
     if (build.phase === 'failed') {
         if (build.log_tail) {
             (0, ui_1.out)();
@@ -180,20 +174,94 @@ async function deploy(args) {
     // 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.
     let functions = null;
-    try {
-        functions = await refreshPlatformEnv(root, client, config.projectId);
-    }
-    catch {
-        (0, ui_1.warn)('Could not refresh the function addresses in .env, the build itself is fine');
+    if (root !== null) {
+        try {
+            functions = await refreshPlatformEnv(root, client, projectId);
+        }
+        catch {
+            (0, ui_1.warn)('Could not refresh the function addresses in .env, the build itself is fine');
+        }
     }
+    // A project without a site has no pages to publish, and its functions went live
+    // with this very build. Naming publish there sends the reader to a refusal.
+    const hasSite = started.has_site !== false;
     if (functions === null) {
-        (0, ui_1.note)((0, ui_1.dim)('  The cloud functions of this build are already live: publishing does not hold them back'));
+        (0, ui_1.note)((0, ui_1.dim)('  The cloud functions of this build are already live'));
+        if (hasSite)
+            (0, ui_1.note)((0, ui_1.dim)('  Publishing does not hold them back'));
     }
     else if (functions.length > 0) {
         (0, ui_1.note)((0, ui_1.dim)(`  Cloud functions live now: ${functions.join(', ')}`));
-        (0, ui_1.note)((0, ui_1.dim)('  There is one copy per project, publishing does not hold them back'));
+        if (hasSite)
+            (0, ui_1.note)((0, ui_1.dim)('  There is one copy per project, publishing does not hold them back'));
     }
-    (0, ui_1.note)((0, ui_1.dim)('  Show the new pages to visitors: xflow publish'));
+    if (hasSite)
+        (0, ui_1.note)((0, ui_1.dim)('  Show the new pages to visitors: xflow publish'));
+}
+/**
+ * Build a revision the platform already holds: this is how a version comes back.
+ *
+ * The sources of revision N are on the server, so nothing goes up and no copy of
+ * them is needed next to the caller. That also means `--force` has nothing to
+ * force: the revision on the server stays the newest one, and this build simply
+ * runs an older one. The project can therefore be named by id, which is the only
+ * way to bring back the version of a standalone function: its folder may live on
+ * another machine entirely, and there is nothing else to roll back with, because
+ * a project without a site has no pages to return.
+ */
+async function deployRevision(args, revision, comment) {
+    const { projectId, client, root } = await (0, session_1.projectTarget)(args);
+    await assertBuildAllowed(client, projectId);
+    (0, ui_1.step)(`Building on the platform from revision ${revision}`);
+    const started = await startBuild(client, projectId, revision, (0, args_1.flagBool)(args, 'allow-removals'), comment);
+    await finishBuild(client, projectId, started, root);
+}
+/**
+ * The revision named by --revision, with the two rules that guard such a build.
+ *
+ * Kept pure and read before anything else: a wrong number or a flag that cannot
+ * apply is worth saying before the version comment is asked for, and a rule like
+ * this deserves a test that needs no platform to talk to.
+ */
+function statedRevision(revision, force) {
+    if (revision === undefined)
+        return undefined;
+    // flagNumber already refuses anything but a whole number, so zero is what is
+    // left to catch here: revisions are counted from one.
+    if (revision < 1) {
+        throw new errors_1.CliError(`--revision takes a revision number, got "${revision}"`, 'The revision of each version: xflow deployments');
+    }
+    if (force) {
+        throw new errors_1.CliError('--force does not apply to --revision', 'Nothing is sent: the build runs the sources the platform already holds');
+    }
+    return revision;
+}
+async function deploy(args) {
+    const stated = statedRevision((0, args_1.flagNumber)(args, 'revision'), (0, args_1.flagBool)(args, 'force'));
+    const comment = requireComment(args);
+    if (stated !== undefined)
+        return deployRevision(args, stated, comment);
+    if ((0, args_1.flagString)(args, 'project') !== undefined) {
+        throw new errors_1.CliError('xflow deploy sends the sources next to it, so it runs in the project folder', 'Name a project by id only to build a revision it already has: xflow deploy --project <id> --revision <n> -m "what came back"');
+    }
+    const { root, config } = (0, config_1.requireProject)();
+    const client = await (0, session_1.connectProject)(config.projectId, root, config);
+    let revision;
+    if ((0, args_1.flagBool)(args, 'no-push')) {
+        const server = await (0, sources_1.latestRevision)(client, config.projectId);
+        if (!server) {
+            throw new errors_1.CliError('The server holds no sources', 'Repeat without --no-push, so that the sources go up first');
+        }
+        revision = server.revision;
+        (0, ui_1.warn)(`Sources not sent (--no-push), the build runs from revision ${revision}`);
+    }
+    else {
+        await assertBuildAllowed(client, config.projectId);
+        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'), comment);
+    await finishBuild(client, config.projectId, started, root);
 }
 async function publish(args) {
     const { projectId, client } = await (0, session_1.projectTarget)(args);

package/dist/commands/dev.js

@@ -30,7 +30,7 @@ async function dev() {
     // project token, would reach this run only after one of them.
     try {
         const card = await (0, api_1.apiJson)(client, `/api/v1/projects/${config.projectId}`);
-        Object.assign(env, (0, template_1.platformEnv)(card.project_token, client.apiUrl, card.functions));
+        Object.assign(env, (0, template_1.platformEnv)(card.project_token, client.apiUrl, card.functions, card.function_map));
     }
     catch (e) {
         (0, ui_1.warn)(`The function addresses were not fetched (${e instanceof Error ? e.message : String(e)}): the ones in .env are used`);

package/dist/commands/projects.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.templates = templates;
+exports.functionNameFrom = functionNameFrom;
 exports.init = init;
 exports.link = link;
 exports.list = list;
@@ -48,6 +49,66 @@ async function templates() {
     }
     (0, ui_1.table)(list.map((t) => [t.id, t.name, t.is_default ? 'default' : '', t.description ?? '']));
 }
+/**
+ * A function name out of the project name: the platform takes lowercase latin
+ * letters, digits and dashes, and the folder it lives in gives it its name.
+ */
+function functionNameFrom(name) {
+    const slug = name
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 41);
+    if (!/^[a-z0-9][a-z0-9-]{0,40}$/.test(slug)) {
+        throw new errors_1.CliError(`Cannot make a function name out of "${name}"`, 'Name it in latin letters, digits and dashes: xflow init my-fn --function');
+    }
+    return slug;
+}
+/**
+ * Create a standalone function: a shared backend of the organization, a project
+ * without a site. No template is fetched — there is no frontend to fetch.
+ */
+async function initFunction(args, client, target, name) {
+    const functionName = functionNameFrom(name);
+    (0, ui_1.step)('Creating the function on the platform');
+    const project = await (0, api_1.apiJson)(client, '/api/v1/projects', {
+        method: 'POST',
+        body: {
+            name,
+            kind: 'function',
+            database_id: (0, args_1.flagString)(args, 'database') ?? null,
+            server: (0, args_1.flagString)(args, 'server') ?? null,
+        },
+        timeoutMs: 60_000,
+    });
+    try {
+        (0, node_fs_1.mkdirSync)(target, { recursive: true });
+        for (const file of (0, template_1.functionScaffoldFiles)(name, functionName))
+            write(target, file.path, file.content);
+        // No build block: the platform builds the functions of such a project and
+        // never its site, so a build command would be a promise nobody keeps.
+        (0, config_1.writeConfig)(target, { projectId: project.id });
+        (0, config_1.ignoreStateInGit)(target);
+        if (client.organizationId)
+            (0, config_1.writeState)(target, { organizationId: client.organizationId });
+    }
+    catch (e) {
+        (0, ui_1.note)((0, ui_1.dim)(`  The function "${project.name}" is already created (${project.id}).`));
+        (0, ui_1.note)((0, ui_1.dim)('  Sort the folder out and pick it up: xflow link ' + project.id));
+        throw e;
+    }
+    (0, skills_1.installSkillQuietly)(target);
+    (0, ui_1.ok)(`Function "${project.name}" created: functions/${functionName}`);
+    if (project.database) {
+        const { server } = project.database;
+        (0, ui_1.note)((0, ui_1.dim)(`  Its database "${project.database.name}" is on ${server ? `own "${server.name}"` : 'the platform server'}`));
+    }
+    (0, ui_1.out)('');
+    (0, ui_1.out)(`  ${(0, ui_1.bold)('Next:')}`);
+    (0, ui_1.out)(`    cd ${(0, node_path_1.basename)(target)}`);
+    (0, ui_1.out)('    npm install');
+    (0, ui_1.out)('    xflow deploy       # send the code, build and release the function');
+}
 /** Create a project from the platform template. */
 async function init(args) {
     const target = (0, node_path_1.resolve)(args.words[0] ?? '.');
@@ -56,6 +117,8 @@ async function init(args) {
     if (!isEmptyEnough(target)) {
         throw new errors_1.CliError(`The directory ${target} is not empty`, 'Create the project in an empty folder: xflow init my-app. To link an existing folder to a project: xflow link <id>');
     }
+    if ((0, args_1.flagBool)(args, 'function'))
+        return initFunction(args, client, target, name);
     let templateId = (0, args_1.flagString)(args, 'template');
     if (!templateId) {
         const { templates: list } = await (0, api_1.apiJson)(client, '/api/v1/templates');
@@ -164,7 +227,7 @@ async function link(args) {
     (0, config_1.ignoreStateInGit)(dir);
     if (client.organizationId)
         (0, config_1.writeState)(dir, { organizationId: client.organizationId });
-    (0, template_1.writePlatformEnv)(dir, card.project_token, client.apiUrl, card.functions);
+    (0, template_1.writePlatformEnv)(dir, card.project_token, client.apiUrl, card.functions, card.function_map);
     (0, ui_1.note)((0, ui_1.dim)('  .env now points at this project, run it locally with xflow dev'));
     const skillReady = (0, skills_1.installSkillQuietly)(dir);
     (0, ui_1.ok)(`The folder is linked to the project "${card.name}"`);
@@ -202,7 +265,15 @@ async function list() {
         (0, ui_1.table)(projects.map((p) => [
             p.id,
             p.name,
-            p.live_deploy_id ? 'published' : p.dev_deploy_id ? 'dev only' : 'no build',
+            // A standalone function has no pages at all, so the states of a site
+            // ("published", "dev only") would say nothing about it.
+            p.kind === 'function'
+                ? 'function'
+                : p.live_deploy_id
+                    ? 'published'
+                    : p.dev_deploy_id
+                        ? 'dev only'
+                        : 'no build',
             (0, ui_1.formatAge)(p.updated_at),
         ]));
     }

package/dist/flags.js

@@ -21,6 +21,10 @@ const help_1 = require("./help");
  * only when that command can answer without the working copy. The ones that cannot
  * have a folder to stand in, and naming a project they cannot read would be a lie;
  * they are listed in WORKING_COPY below, each with what it reads from that folder.
+ * `deploy` sits halfway and keeps the flag: sending the sources needs the folder,
+ * but building a revision the platform already holds (`--revision`) does not, and
+ * it is the only way to bring back the version of a project without pages. Named
+ * by id without `--revision` it refuses, in those words.
  * `db status` sits halfway: named by id it answers with the applied history alone,
  * without the comparison against migrations/. `connections unlink` sits there too:
  * by id it removes the link without the check of what reads the variables, because
@@ -40,7 +44,7 @@ exports.KNOWN = {
     'org members': [],
     'org switch': [],
     templates: [],
-    init: ['name', 'template', 'database', 'server'],
+    init: ['name', 'template', 'database', 'server', 'function'],
     link: [],
     projects: [],
     'projects list': [],
@@ -91,7 +95,7 @@ exports.KNOWN = {
     status: [],
     dev: [],
     pull: ['into', 'force', 'revision'],
-    deploy: ['no-push', 'force', 'allow-removals', 'message'],
+    deploy: ['no-push', 'force', 'allow-removals', 'message', 'revision', 'project'],
     publish: ['project'],
     rollback: ['project'],
     deployments: ['project'],
@@ -110,7 +114,6 @@ exports.KNOWN = {
  * line here, or a refusal nobody prints any more stays behind as a lie.
  */
 exports.WORKING_COPY = {
-    deploy: 'it sends the sources next to it',
     pull: 'it writes the sources next to it',
     status: 'it compares the folder with the revision on the platform',
     dev: 'it runs the dev server of the code next to it',

package/dist/help.js

@@ -168,14 +168,17 @@ Which commands: ${(0, ui_1.bold)('db status')}, ${(0, ui_1.bold)('db query')}, $
 ${(0, ui_1.bold)('functions invoke')}, ${(0, ui_1.bold)('functions logs')}, ${(0, ui_1.bold)('logs')}, ${(0, ui_1.bold)('env')}, ${(0, ui_1.bold)('env rm')},
 ${(0, ui_1.bold)('connections')}, ${(0, ui_1.bold)('connections link')}, ${(0, ui_1.bold)('connections unlink')}, ${(0, ui_1.bold)('schedules')},
 ${(0, ui_1.bold)('schedules set')}, ${(0, ui_1.bold)('schedules rm')}, ${(0, ui_1.bold)('storage ls')}, ${(0, ui_1.bold)('storage push')},
-${(0, ui_1.bold)('storage rm')}, ${(0, ui_1.bold)('deployments')}, ${(0, ui_1.bold)('publish')}, ${(0, ui_1.bold)('rollback')}. Two of them
-answer with less under the flag: ${(0, ui_1.bold)('db status')} gives the applied history alone,
+${(0, ui_1.bold)('storage rm')}, ${(0, ui_1.bold)('deployments')}, ${(0, ui_1.bold)('publish')}, ${(0, ui_1.bold)('rollback')}, ${(0, ui_1.bold)('deploy')}. Three of
+them answer with less under the flag: ${(0, ui_1.bold)('db status')} gives the applied history alone,
 because comparing it against the local ${(0, ui_1.bold)('migrations/')} directory needs the folder,
-and ${(0, ui_1.bold)('connections unlink')} removes the link without naming the functions that read
-its variables, for the same reason.
+${(0, ui_1.bold)('connections unlink')} removes the link without naming the functions that read
+its variables, for the same reason, and ${(0, ui_1.bold)('deploy')} takes the flag only together with
+${(0, ui_1.bold)('--revision')}: that build runs a revision the platform already holds, so there is
+nothing to send and no folder to send it from. Without ${(0, ui_1.bold)('--revision')} it refuses and
+says so.
 
 The rest cannot answer without the working copy and have nothing to do with an id
-instead: ${(0, ui_1.bold)('deploy')}, ${(0, ui_1.bold)('pull')}, ${(0, ui_1.bold)('status')}, ${(0, ui_1.bold)('dev')}, ${(0, ui_1.bold)('db migrate')},
+instead: ${(0, ui_1.bold)('pull')}, ${(0, ui_1.bold)('status')}, ${(0, ui_1.bold)('dev')}, ${(0, ui_1.bold)('db migrate')},
 ${(0, ui_1.bold)('env check')}, ${(0, ui_1.bold)('env set')}. They answer about the files next to them, so
 they keep asking for a folder. ${(0, ui_1.bold)('projects get')} and ${(0, ui_1.bold)('link')} take no flag either:
 they name the project by its id as an argument.
@@ -306,8 +309,9 @@ attached to each one. That last column is the one to read before a migration. Th
 column says where a database lives: ${(0, ui_1.bold)('platform')} is the common one, ${(0, ui_1.bold)('own "<name>"')} the
 organization's own server. While an own server is not running, its databases do not
 answer, and that is not fixable from the code: its state is in the web interface. An
-organization with own servers also gets them listed, with the room used on each and the
-one new databases go to: that is the choice for ${(0, ui_1.bold)('xflow init --server')} and ${(0, ui_1.bold)('db move')}.
+organization with own servers also gets them listed, with the room used on each: that is
+the choice for ${(0, ui_1.bold)('xflow init --server')} and ${(0, ui_1.bold)('db move')}. Without that flag a new
+database goes to ${(0, ui_1.bold)('platform')}.
 
 ${(0, ui_1.bold)('move')} takes the database of this project to another server of the organization:
 ${(0, ui_1.bold)('platform')} or an own server by name (or id, when two share a name). The platform copies
@@ -661,6 +665,9 @@ by default).
                      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
+  --revision <N>     build a revision the platform already holds: this is how a
+                     version comes back (the list: xflow deployments)
+  --project <id>     with --revision only: the project to rebuild, no folder needed
   --force            allow overwriting the server revision while sending
   --allow-removals   agree in advance to remove the functions gone from the sources
 
@@ -703,7 +710,15 @@ 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
-old copy.`,
+old copy.
+
+${(0, ui_1.bold)('--revision <N>')} brings a version back. The sources of that revision are already on
+the server, so nothing goes up, no copy of them is needed next to you and the newest
+revision stays the newest: this build simply runs an older one. Since there is no folder
+to stand in, the project can be named by id (${(0, ui_1.bold)('--project')}), and for a standalone
+function that is the only way back: it has no pages, so ${(0, ui_1.bold)('xflow rollback')} has nothing
+to return. Functions that exist now but not in that revision would be removed, and the
+same question is asked as in any other deploy.`,
     init: `${(0, ui_1.bold)('xflow init')} [dir]: a new project
 
 Lays down the platform template: React on Vite, Tailwind, a set of components
@@ -716,14 +731,21 @@ Building the interface on top of these components and the tokens in ${(0, ui_1.b
 is not a formality: your own palette on top of them looks foreign inside the platform.
 
   --name <name>       project name (the folder name by default)
+  --function          a standalone function instead of an application
   --template <id>     a different template (the list: xflow templates)
   --database <id>     attach a logical database of the organization (the list: xflow db list)
   --server <name>     a new database for the project, right away on that server:
                       platform, or an own server of the organization (xflow db list)
 
+${(0, ui_1.bold)('--function')} makes a shared backend of the organization: a project without a site,
+with one handler in ${(0, ui_1.bold)('functions/<name>/index.ts')} and no template to fetch. Any
+application of the organization calls it; who exactly is allowed in is decided by
+${(0, ui_1.bold)('minRole')} inside the function. It builds and releases with the same deploy, but
+there are no pages to publish, so publish and rollback do not apply to it.
+
 Without either flag the project gets its database with the first migration, on the
-server new databases of the organization go to. ${(0, ui_1.bold)('--server')} decides it up front: the
-server has to be running, and the database counts against the plan at once.
+platform server. ${(0, ui_1.bold)('--server')} decides it up front: the server has to be running, and
+the database counts against the plan at once.
 
 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

package/dist/template.js

@@ -4,6 +4,7 @@ exports.envApiUrl = envApiUrl;
 exports.platformEnv = platformEnv;
 exports.writePlatformEnv = writePlatformEnv;
 exports.scaffoldFiles = scaffoldFiles;
+exports.functionScaffoldFiles = functionScaffoldFiles;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const GITIGNORE = `node_modules/
@@ -45,19 +46,22 @@ function envApiUrl(apiUrl) {
     return apiUrl.replace(/^https?:\/\//, '');
 }
 /** The variables that point a local run at the project: written to .env, handed to xflow dev. */
-function platformEnv(projectToken, apiUrl, functions = []) {
+function platformEnv(projectToken, apiUrl, functions = [], 
+// The map the platform assembled: it also holds the standalone functions of the
+// organization. Own functions alone are the fallback for a platform without it.
+map) {
     return {
         VITE_XFLOW_PROJECT_TOKEN: projectToken ?? '',
         VITE_XFLOW_API_URL: envApiUrl(apiUrl),
-        [FUNCTIONS_ENV_KEY]: functionsEnvValue(functions),
+        [FUNCTIONS_ENV_KEY]: map ? JSON.stringify(map) : functionsEnvValue(functions),
     };
 }
 /**
  * Point .env at the current project: written on every link and deploy, so that `npm run dev`
  * never keeps talking to the previous one. Variables of your own are left alone.
  */
-function writePlatformEnv(root, projectToken, apiUrl, functions = []) {
-    for (const [key, value] of Object.entries(platformEnv(projectToken, apiUrl, functions))) {
+function writePlatformEnv(root, projectToken, apiUrl, functions = [], map) {
+    for (const [key, value] of Object.entries(platformEnv(projectToken, apiUrl, functions, map))) {
         writeEnvValue(root, key, value);
     }
 }
@@ -81,3 +85,57 @@ function scaffoldFiles(projectName) {
         { path: 'README.md', content: README.replace('%NAME%', projectName.replace(/"/g, '\\"')) },
     ];
 }
+/**
+ * A standalone function has no site, so it gets no Vite tree: one handler, and
+ * esbuild, which the sandbox takes from the project to bundle the function.
+ */
+const FUNCTION_HANDLER = `/**
+ * Cloud function of the %NAME% project.
+ *
+ * XFlow calls it over HTTP and, if a schedule is set, on a timer. The answer is
+ * { statusCode, body }, where body is a string.
+ */
+export async function handler(event: {
+  httpMethod: string;
+  body: string | null;
+  queryStringParameters: Record<string, string> | null;
+}) {
+  const input = event.body ? JSON.parse(event.body) : {};
+
+  return {
+    statusCode: 200,
+    body: JSON.stringify({ ok: true, method: event.httpMethod, input }),
+  };
+}
+`;
+const FUNCTION_README = `# %NAME%
+
+A standalone function on XFlow: a shared backend for the applications of the
+organization, without a site of its own.
+
+\`\`\`bash
+npm install       # dependencies
+xflow deploy      # send the code, build and release the function
+xflow functions   # its address and status
+\`\`\`
+
+The code lives in \`functions/%FUNCTION%/index.ts\`. A schedule, keys and secrets
+are set in the platform, in the "Functions" section.
+`;
+function functionScaffoldFiles(projectName, functionName) {
+    const fill = (text) => text.replace(/%NAME%/g, projectName.replace(/"/g, '\\"')).replace(/%FUNCTION%/g, functionName);
+    return [
+        { path: '.gitignore', content: GITIGNORE },
+        { path: 'README.md', content: fill(FUNCTION_README) },
+        {
+            path: 'package.json',
+            content: `${JSON.stringify({
+                name: functionName,
+                private: true,
+                type: 'module',
+                devDependencies: { esbuild: '0.28.2' },
+            }, null, 2)}\n`,
+        },
+        { path: `functions/${functionName}/index.ts`, content: fill(FUNCTION_HANDLER) },
+    ];
+}

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

package/skills/xflow/SKILL.md

@@ -22,7 +22,7 @@ contains the fix.
 
 ## Keeping these instructions current
 
-These instructions ship with xflow CLI 0.29.0, so the copy you are reading can be older than
+These instructions ship with xflow CLI 0.30.0, so the copy you are reading can be older than
 the CLI answering your commands.
 
 When the CLI says this file does not match it, run `xflow skills --refresh` and then **read
@@ -123,6 +123,12 @@ the pages of an earlier build. Only the pages come back and they talk to today's
 code of that build is a separate fetch (`xflow pull --revision N --into ../old-version`, kept
 outside the project folder); building it over the current one needs a human.
 
+Bringing the code back instead of the pages: `xflow deploy --revision N -m "what came back"`
+builds a revision the platform already holds. Nothing goes up, so no copy of that code is needed
+next to you and the newest revision stays the newest. It is the only way back for a standalone
+function, which has no pages to return, and it needs no folder at all: `--project <id>` names the
+project. Functions that exist now but not in that revision are removed, with the usual question.
+
 Pages are kept for the **three latest successful builds** plus whatever dev and live show;
 older versions stay in the history with `pages_kept` false, readable but not openable. The
 history holds the **last 30 builds**, each keeping the revision it was built from; any other
@@ -216,6 +222,28 @@ There is no separate deploy command: `xflow deploy` ships the functions and then
 application, in that order. `xflow functions list` shows what is live. The handler returns
 `{ statusCode, body }` where `body` is a JSON string.
 
+A function that belongs to no single application is created on its own: `xflow init <dir>
+--function` makes a project without a site, with one handler and no template. It is a shared
+backend of the organization, and any application of that organization calls it; who is let in
+is decided by `minRole` inside the function. Deploy builds and releases it the same way, but it
+has no pages, so `xflow publish` and `xflow rollback` do not apply; an earlier version comes back
+with `xflow deploy --revision N`. It counts against the plan
+limit of functions, not of applications. Put a function here when it serves several
+applications, a bot or a webhook; a function serving one application belongs in that project.
+
+An application calls it like its own: `xflow.functions.invoke('<name>')`, the platform puts the
+address into the map the bundle carries. Two things follow from that map. An application sees a
+newly created standalone function only after its own `xflow deploy`, and a function of the
+project always wins a name it shares with a standalone one: the deploy names such a name in its
+output, and the shared function stays unreachable from that project until one of them is
+renamed. Such a call carries a person: a server key of another project opens the functions of
+its own project only.
+
+Inside a standalone function, remember who can reach it: any member of the organization,
+including someone whose access to projects is narrowed to one folder. The role in `minRole` is
+the role in the organization, so a function holding data that is not for everyone checks the
+caller itself (`event.xflow.user`).
+
 Keep one shape inside that string across the whole project: `{ success: true, data }`
 when it worked, `{ success: false, error: { message, code } }` when it did not. Nothing
 enforces this, but a project where every function answers its own way costs an adapter
@@ -290,7 +318,8 @@ answers 401.
 
 An outside service (a payment webhook, a bot, a CRM) has no person behind it and needs a key of
 that one function. Keys are not issued by default and the CLI cannot create one: a human issues
-it in the project settings, «Облачные функции» → the function → «Настройки». Ask the user to do
+it in the project settings, «Облачные функции» → the function → «Настройки»; a standalone
+function has a screen of its own, «Функции» → the function → «Настройки». Ask the user to do
 that and to paste the address back — never invent another way in. Send it in the
 `X-Function-Key` header. A function holds at most two keys, the second one to replace the first
 without downtime, not to serve a second consumer.
@@ -437,16 +466,17 @@ strips them from arguments. Look before you write a migration against a shared d
 
 An organization can have own database servers, several of them for different jobs. `xflow db
 list` names the server of each database (`platform` is the common one) and lists the own servers
-with the room used and the one new databases go to; `xflow db status` names the one under this
-project. The server belongs to the database: projects sharing a database share its server.
+with the room used; `xflow db status` names the one under this project. The server belongs to the
+database: projects sharing a database share its server.
 - A new project with its database on a chosen server: `xflow init --server <name>` (`platform`
-  for the common one). Without it the first migration creates the database where new ones go.
+  for the common one). Without it the first migration creates the database on `platform`.
 - An existing database: `xflow db move --to <name> --confirm <database name>`. Writes to every
   project on it close while it copies, usually a couple of minutes; the platform switches the
   functions itself, no deploy. It needs the right to move databases, off on the key by default:
   refused for the right, say what should move where and why, and the person turns it on or
   moves it in the "Data" section.
-- Buying, paying for and deleting servers are the person's, in the web interface.
+- Buying, paying for and deleting servers are the person's, in the web interface. There is no
+  limit on how many. If a database has outgrown its server, say so and suggest buying one.
 
 Code stays the same: `DATABASE_URL` arrives as before, pass it as is, without an `ssl` option (an
 own server is reached over a closed network, and `ssl` makes the connection fail). While an own
@@ -454,6 +484,23 @@ server is not running, migrations and queries say so and functions that use the
 out. That is not your code and not yours to fix: tell the person, who sees the server state in
 the "Data" section of the web interface, instead of retrying.
 
+An own server comes tuned and guarded, so do not tune it from migrations:
+- Installed from the start: `pgcrypto`, `pg_trgm`, `unaccent`, `citext`, `btree_gin`,
+  `btree_gist`, `pg_stat_statements`. Use them, do not `CREATE EXTENSION` them again. UUIDs
+  need no extension anywhere: `gen_random_uuid()` is built in, and on an own server so is
+  `uuidv7()`. Never `uuid-ossp`. Anything else (`postgis`, `pgvector`) is a request to the
+  person, not a migration.
+- Limits on every connection: a statement is cut after 30 seconds, waiting for a lock after 3,
+  a transaction left open after 30. A query that needs longer is a wrong query (an index is
+  missing, or it is a report that belongs in a scheduled function writing a summary table). A
+  migration that needs longer is split into smaller ones. The one exception is a scheduled job
+  that genuinely needs more: it runs `SET statement_timeout = '5min'` on its own connection,
+  and nowhere else. A database that used `citext` or another extension type cannot move back to
+  `platform`: the move refuses, the common server has no such extensions.
+- A restart happens on a plan change and takes about a minute. Create the `Client` inside the
+  handler, or keep a `Pool` at module level: a `Client` created at module level dies with the
+  restart and stays dead until the function cold-starts.
+
 ## File storage
 
 Two kinds of files live here, and they arrive through different doors.