@getxflow/cli 0.28.0 → 0.30.0

package/dist/api.js

@@ -16,7 +16,9 @@ class ApiError extends Error {
     limit;
     removing;
     request;
-    constructor(message, code, status, hint, details = {}) {
+    /** The platform that answered: its signed-in organizations are the ones worth naming. */
+    apiUrl;
+    constructor(message, code, status, hint, details = {}, apiUrl) {
         super(message);
         this.name = 'ApiError';
         this.code = code;
@@ -26,6 +28,7 @@ class ApiError extends Error {
         this.limit = details.limit;
         this.removing = details.removing;
         this.request = details.request;
+        this.apiUrl = apiUrl;
     }
 }
 exports.ApiError = ApiError;
@@ -126,7 +129,7 @@ async function readError(response, client) {
     const text = await response.text().catch(() => '');
     try {
         const parsed = JSON.parse(text);
-        return new ApiError(parsed.error || `Request rejected (${response.status})`, parsed.code || 'unknown', response.status, parsed.hint, parsed);
+        return new ApiError(parsed.error || `Request rejected (${response.status})`, parsed.code || 'unknown', response.status, parsed.hint, parsed, client.apiUrl);
     }
     catch {
         return notAnAnswer(response.status, client.apiUrl, text);

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

@@ -176,11 +176,15 @@ async function run(args) {
                 await (0, db_1.dbQuery)({ ...args, words: args.words.slice(2) });
                 return;
             }
+            if (second === 'move') {
+                await (0, db_1.dbMove)(rest);
+                return;
+            }
             if (second === undefined || second === 'status') {
                 await (0, db_1.dbStatus)({ ...args, words: args.words.slice(2) });
                 return;
             }
-            throw new errors_1.CliError(`Unknown command: db ${second}`, 'Available: status, list, schema, query and migrate');
+            throw new errors_1.CliError(`Unknown command: db ${second}`, 'Available: status, list, schema, query, migrate and move');
         case 'storage':
             if (second === 'push') {
                 await (0, storage_1.storagePush)(rest);
@@ -327,7 +331,7 @@ async function main() {
                 if (process.env.XFLOW_TOKEN?.trim()) {
                     (0, ui_1.fatalNote)((0, ui_1.dim)('  XFLOW_TOKEN is set: it is the key of one organization and is used as it comes, so a project or a page of another one is not found'));
                 }
-                else if ((0, credentials_1.anyMultipleOrgs)()) {
+                else if (e.apiUrl && (0, credentials_1.listOrgs)(e.apiUrl).length > 1) {
                     (0, ui_1.fatalNote)((0, ui_1.dim)('  Several organizations are signed in: the answer may live in another one, see xflow org'));
                 }
             }

package/dist/commands/db.js

@@ -4,6 +4,7 @@ exports.dbStatus = dbStatus;
 exports.dbList = dbList;
 exports.dbSchema = dbSchema;
 exports.dbQuery = dbQuery;
+exports.dbMove = dbMove;
 exports.dbMigrate = dbMigrate;
 const node_fs_1 = require("node:fs");
 const node_crypto_1 = require("node:crypto");
@@ -24,12 +25,34 @@ function serverLabel(server) {
         return 'platform';
     return server.status === 'active' ? `own "${server.name}"` : `own "${server.name}", ${server.status}`;
 }
-function printPlace(history) {
+const moving = (move) => move?.status === 'copying' || move?.status === 'switching';
+/** Asked apart from the history: during a move the database does not answer, this does. */
+async function projectDatabase(client, projectId) {
+    try {
+        return await (0, api_1.apiJson)(client, `/api/v1/projects/${projectId}/db/move`);
+    }
+    catch (e) {
+        if (e instanceof api_1.ApiError && e.code === 'not_deployed')
+            return null;
+        throw e;
+    }
+}
+function printPlace(history, place) {
     (0, ui_1.out)(`Schema: ${(0, ui_1.bold)(history.schema)}`);
     if (history.server !== undefined)
         (0, ui_1.out)(`Server: ${serverLabel(history.server)}`);
+    if (place?.move)
+        (0, ui_1.out)(`Move:   ${moveLine(place.move)}`);
     (0, ui_1.out)('');
 }
+/** Mid-move the history cannot be read, so the answer is the move itself. */
+function printMoving(place) {
+    if (place.database)
+        (0, ui_1.out)(`Database: ${(0, ui_1.bold)(place.database.name)}`);
+    (0, ui_1.out)(`Server:   ${serverLabel(place.server)}`);
+    (0, ui_1.out)(`Move:     ${place.move?.note ?? ''}`);
+    (0, ui_1.note)((0, ui_1.dim)('  Migrations and queries wait until it is over; the platform finishes it on its own'));
+}
 function checksum(sql) {
     return (0, node_crypto_1.createHash)('sha256').update(sql).digest('hex').slice(0, 16);
 }
@@ -58,8 +81,11 @@ async function dbStatus(args) {
     // is the applied history alone, which does not depend on any working copy.
     if ((0, args_1.flagString)(args, 'project') !== undefined) {
         const { projectId, client } = await (0, session_1.projectTarget)(args);
+        const place = await projectDatabase(client, projectId);
+        if (place && moving(place.move))
+            return printMoving(place);
         const history = await (0, api_1.apiJson)(client, `/api/v1/projects/${projectId}/db/migrate`);
-        printPlace(history);
+        printPlace(history, place);
         if (history.applied.length === 0) {
             (0, ui_1.note)('No migrations have been applied yet');
             return;
@@ -71,9 +97,12 @@ async function dbStatus(args) {
     const { root, config } = (0, config_1.requireProject)();
     const client = await (0, session_1.connectProject)(config.projectId, root, config);
     const local = readMigrations(root);
+    const place = await projectDatabase(client, config.projectId);
+    if (place && moving(place.move))
+        return printMoving(place);
     const history = await (0, api_1.apiJson)(client, `/api/v1/projects/${config.projectId}/db/migrate`);
     const applied = new Map(history.applied.map((row) => [row.name, row]));
-    printPlace(history);
+    printPlace(history, place);
     if (local.length === 0 && applied.size === 0) {
         (0, ui_1.note)(`No migrations. The first one: ${MIGRATIONS_DIR}/0001_init.sql`);
         return;
@@ -104,6 +133,18 @@ async function dbStatus(args) {
         (0, ui_1.warn)('A changed file will not be applied again: write a new migration');
     }
 }
+function serverRow(server) {
+    const room = server.used_bytes !== null && server.space_bytes !== null
+        ? `${(0, ui_1.formatBytes)(server.used_bytes)} of ${(0, ui_1.formatBytes)(server.space_bytes)} used`
+        : '';
+    return [
+        server.id === null ? 'platform' : `own "${server.name}"`,
+        server.id === null ? 'plan space' : server.tier ?? '',
+        server.status === 'active' ? '' : server.status,
+        room,
+        `${server.databases} ${server.databases === 1 ? 'database' : 'databases'}`,
+    ];
+}
 function attachedProjects(database) {
     const names = database.projects.map((project) => project.name);
     if (database.hidden_projects > 0)
@@ -123,24 +164,34 @@ async function dbList() {
     if (data.databases.length === 0) {
         (0, ui_1.note)('The organization has no databases');
         (0, ui_1.note)((0, ui_1.dim)('  One is created with the first project: xflow init'));
-        return;
     }
-    (0, ui_1.table)(data.databases.map((database) => [
+    else {
+        printDatabases(data.databases, data.total, data.truncated);
+    }
+    printServers(data.servers);
+}
+function moveLine(move) {
+    return move.finished_at ? `${move.note} (${(0, ui_1.formatAge)(move.finished_at)})` : move.note;
+}
+function printDatabases(databases, total, truncated) {
+    (0, ui_1.table)(databases.map((database) => [
         database.name,
         database.id,
         database.schema ?? '-',
         serverLabel(database.server),
         attachedProjects(database),
     ]));
-    if (data.truncated)
-        (0, ui_1.note)((0, ui_1.dim)(`  Shown ${data.databases.length} of ${data.total}`));
-    for (const database of data.databases) {
+    if (truncated)
+        (0, ui_1.note)((0, ui_1.dim)(`  Shown ${databases.length} of ${total}`));
+    for (const database of databases) {
         const attached = database.projects.length + database.hidden_projects;
         if (attached > 1)
             (0, ui_1.note)((0, ui_1.dim)(`  ${database.name} is shared by ${attached} projects: a migration affects all of them`));
+        if (database.move)
+            (0, ui_1.note)((0, ui_1.dim)(`  ${database.name}: ${moveLine(database.move)}`));
     }
     const down = new Map();
-    for (const { server } of data.databases)
+    for (const { server } of databases)
         if (server && server.status !== 'active')
             down.set(server.id, server);
     for (const server of down.values()) {
@@ -148,6 +199,15 @@ async function dbList() {
             'Not fixable from the code: tell the person, the server state is in the "Data" section of the web interface'));
     }
 }
+/** Where a new or a moved database can go, with the room on each. Only the platform: no choice to show. */
+function printServers(servers) {
+    if (!servers || servers.length < 2)
+        return;
+    (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)('  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;
 function plain(value) {
@@ -255,6 +315,62 @@ async function dbQuery(args) {
             : `  Shown the first ${data.rows.length} rows, more exist: narrow the query, with a where clause or an offset`));
     }
 }
+const MOVE_POLL_MS = 3_000;
+/** Past this the command lets go: the move carries on, db status follows it. */
+const MOVE_FOLLOW_MS = 10 * 60_000;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Moving the project database to another server of the organization. The platform
+ * runs the move by itself; this command starts it and follows it to the end.
+ */
+async function dbMove(args) {
+    const to = (0, args_1.flagString)(args, 'to');
+    if (!to) {
+        throw new errors_1.CliError('Name the server: --to <name>', 'The servers and their names: xflow db list ("platform" is the common one)');
+    }
+    const { projectId, client } = await (0, session_1.projectTarget)(args);
+    const path = `/api/v1/projects/${projectId}/db/move`;
+    let place;
+    try {
+        place = await (0, api_1.apiJson)(client, path, {
+            method: 'POST',
+            body: { to, confirm: (0, args_1.flagString)(args, 'confirm') },
+            timeoutMs: 60_000,
+        });
+    }
+    catch (e) {
+        // Said in the words of this command: the flag, and the name that goes in it.
+        if (e instanceof api_1.ApiError && e.code === 'confirm_required') {
+            const found = await projectDatabase(client, projectId).catch(() => null);
+            const name = found?.database?.name ?? '<database>';
+            throw new errors_1.CliError(e.message, `To move it: xflow db move --to "${to}" --confirm "${name}"`);
+        }
+        throw e;
+    }
+    (0, ui_1.note)((0, ui_1.dim)('  The platform carries the move through by itself: stopping this command does not stop it'));
+    const deadline = Date.now() + MOVE_FOLLOW_MS;
+    let shown = '';
+    while (moving(place.move)) {
+        const line = place.move?.note ?? '';
+        if (line !== shown)
+            (0, ui_1.step)(line);
+        shown = line;
+        if (Date.now() > deadline) {
+            (0, ui_1.note)('Still going: xflow db status follows it');
+            return;
+        }
+        await sleep(MOVE_POLL_MS);
+        place = await (0, api_1.apiJson)(client, path);
+    }
+    const { move } = place;
+    if (move?.status === 'failed')
+        throw new errors_1.CliError(move.note);
+    if (move && (move.functions_done ?? 0) < (move.functions_total ?? 0)) {
+        (0, ui_1.warn)(move.note);
+        return;
+    }
+    (0, ui_1.ok)(move?.note ?? `The database is on ${serverLabel(place.server)}`);
+}
 async function dbMigrate(args) {
     const { root, config } = (0, config_1.requireProject)();
     const client = await (0, session_1.connectProject)(config.projectId, root, config);

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');
@@ -69,7 +132,8 @@ async function init(args) {
     (0, ui_1.step)('Creating the project on the platform');
     const project = await (0, api_1.apiJson)(client, '/api/v1/projects', {
         method: 'POST',
-        body: { name, database_id: (0, args_1.flagString)(args, 'database') ?? null },
+        body: { name, 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 });
@@ -94,6 +158,10 @@ async function init(args) {
     }
     (0, skills_1.installSkillQuietly)(target);
     (0, ui_1.ok)(`Project "${project.name}" created: ${files.length} template files`);
+    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)}`);
@@ -159,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}"`);
@@ -197,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/credentials.js

@@ -7,7 +7,6 @@ exports.rememberOrgName = rememberOrgName;
 exports.setActiveOrg = setActiveOrg;
 exports.forgetOrg = forgetOrg;
 exports.forgetAllOrgs = forgetAllOrgs;
-exports.anyMultipleOrgs = anyMultipleOrgs;
 exports.pickKey = pickKey;
 exports.storedKeyInputs = storedKeyInputs;
 const node_fs_1 = require("node:fs");
@@ -198,11 +197,6 @@ function forgetAllOrgs(apiUrl) {
     writeStore(store);
     return true;
 }
-/** True when any address holds keys of more than one organization. */
-function anyMultipleOrgs() {
-    const store = readStore();
-    return Object.values(store.orgs ?? {}).some((address) => Object.keys(address.keys).length > 1);
-}
 /**
  * One rule for the whole CLI: XFLOW_TOKEN (default address only) beats the
  * folder's organization, which beats the active one. A folder bound to an

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'],
+    init: ['name', 'template', 'database', 'server', 'function'],
     link: [],
     projects: [],
     'projects list': [],
@@ -75,6 +79,7 @@ exports.KNOWN = {
     'db schema': ['project'],
     'db query': ['limit', 'json', 'project'],
     'db migrate': ['dry-run', 'allow-destructive'],
+    'db move': ['to', 'confirm', 'project'],
     storage: ['json', 'project'],
     'storage ls': ['json', 'project'],
     'storage list': ['json', 'project'],
@@ -90,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'],
@@ -109,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

@@ -88,6 +88,8 @@ ${(0, ui_1.bold)('Database')}
   xflow db query "select ..."     read data, in a read-only transaction
   xflow db migrate [--dry-run] [--allow-destructive]
                                   apply the migrations from migrations/*.sql
+  xflow db move --to <server> --confirm <database>
+                                  move the project database to another server
 
 ${(0, ui_1.bold)('Pages')}
   xflow pages                     public sites of the organization at <name>.xflowpage.ru
@@ -162,18 +164,21 @@ no working copy of its own:
   xflow db query --project 3f2a… "select id, title from tasks where done = false"
   xflow functions invoke kanban --project 3f2a… --data-file card.json
 
-Which commands: ${(0, ui_1.bold)('db status')}, ${(0, ui_1.bold)('db query')}, ${(0, ui_1.bold)('db schema')}, ${(0, ui_1.bold)('functions list')},
+Which commands: ${(0, ui_1.bold)('db status')}, ${(0, ui_1.bold)('db query')}, ${(0, ui_1.bold)('db schema')}, ${(0, ui_1.bold)('db move')}, ${(0, ui_1.bold)('functions list')},
 ${(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.
@@ -295,13 +300,30 @@ will work.`,
                                    --json prints the values whole)
   xflow db query <file>.sql        the same, the query read from a file
   xflow db migrate                 apply migrations/*.sql
+  xflow db move --to <server> --confirm <database>
+                                   move the project database to another server
 
 ${(0, ui_1.bold)('list')} is about the organization, not about this project: it names the logical
 databases, the identifier ${(0, ui_1.bold)('xflow init --database <id>')} asks for, and the projects
 attached to each one. That last column is the one to read before a migration. The server
 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.
+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: 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
+the tables, switches the functions of every project on the database and removes the old
+copy; nothing needs a deploy. While it copies, the applications read data but cannot save
+anything new, usually for a couple of minutes, and that goes for every project on the
+database, which is why ${(0, ui_1.bold)('--confirm')} takes the database name. It also needs the right
+to move databases on the key: off by default, only its owner turns it on, in the platform
+settings where the key permissions live. The command follows the move to the end;
+stopping it does not stop the move, and ${(0, ui_1.bold)('xflow db status')} shows where it stands. A move
+that fails is rolled back: the database stays where it was and works as before. Buying,
+paying for and deleting servers stay with the person, in the web interface.
 
 ${(0, ui_1.bold)('schema')} answers a different question than the ${(0, ui_1.bold)('migrations/')} directory: one logical
 database is shared by several projects, so the files say what you did, and the schema
@@ -643,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
 
@@ -685,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
@@ -698,8 +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
+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/ui.js

@@ -96,7 +96,9 @@ function formatBytes(bytes) {
         return `${bytes} B`;
     if (bytes < 1024 * 1024)
         return `${(bytes / 1024).toFixed(1)} KB`;
-    return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+    if (bytes < 1024 * 1024 * 1024)
+        return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+    return `${(bytes / 1024 / 1024 / 1024).toFixed(1)} GB`;
 }
 function formatAge(iso) {
     if (!iso)

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.28.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.28.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.28.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.
@@ -435,13 +464,42 @@ transaction (50 rows by default, `--limit` up to 300; `--json` prints long value
 with double quotes goes in a `.sql` file outside the project, `xflow db query ../q.sql`: PowerShell
 strips them from arguments. Look before you write a migration against a shared database.
 
-An organization can have its own database server, and its new databases are then created there.
-`xflow db list` names the server of each database (`platform` is the common one), `xflow db
-status` the one under this project. 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 server is not running, migrations and queries say so and
-functions that use the database time 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 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; `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 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. 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
+server is not running, migrations and queries say so and functions that use the database time
+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