@getxflow/cli 1.8.1 → 1.10.0

package/dist/args.js

@@ -21,6 +21,7 @@ exports.BOOLEAN_FLAGS = new Set([
     'dry-run',
     'allow-destructive',
     'allow-removals',
+    'overwrite',
 ]);
 function parseArgs(argv) {
     const words = [];

package/dist/bin.js

@@ -183,11 +183,19 @@ async function run(args) {
                 await (0, logs_1.dbLogs)(args);
                 return;
             }
+            if (second === 'branch' || second === 'branches') {
+                await (0, db_1.dbBranch)({ ...args, words: args.words.slice(2) });
+                return;
+            }
+            if (second === 'restore') {
+                await (0, db_1.dbRestore)(args);
+                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, exec and migrate');
+            throw new errors_1.CliError(`Unknown command: db ${second}`, 'Available: status, list, schema, query, exec, migrate, branch and restore');
         case 'storage':
             if (second === 'push') {
                 await (0, storage_1.storagePush)(rest);

package/dist/commands/db.js

@@ -7,6 +7,8 @@ exports.dbQuery = dbQuery;
 exports.dbExec = dbExec;
 exports.dbMigrate = dbMigrate;
 exports.migrateBeforeDeploy = migrateBeforeDeploy;
+exports.dbBranch = dbBranch;
+exports.dbRestore = dbRestore;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const api_1 = require("../api");
@@ -14,6 +16,7 @@ const args_1 = require("../args");
 const config_1 = require("../config");
 const errors_1 = require("../errors");
 const session_1 = require("../session");
+const moment_1 = require("../moment");
 const text_file_1 = require("../text-file");
 const ui_1 = require("../ui");
 const sources_1 = require("./sources");
@@ -171,7 +174,7 @@ async function dbQuery(args) {
     const { projectId, client } = await (0, session_1.projectTarget)(args);
     const data = await (0, api_1.apiJson)(client, `/api/v1/projects/${projectId}/db/query`, {
         method: 'POST',
-        body: { sql },
+        body: { sql, branch: (0, args_1.flagString)(args, 'branch') },
         timeoutMs: 60_000,
     });
     // The whole values, machine-readable, and the only thing printed: --json silences
@@ -217,7 +220,7 @@ async function dbExec(args) {
     const { projectId, client } = await (0, session_1.projectTarget)(args);
     const data = await (0, api_1.apiJson)(client, `/api/v1/projects/${projectId}/db/exec`, {
         method: 'POST',
-        body: { sql, allow_destructive: (0, args_1.flagBool)(args, 'allow-destructive') },
+        body: { sql, allow_destructive: (0, args_1.flagBool)(args, 'allow-destructive'), branch: (0, args_1.flagString)(args, 'branch') },
         timeoutMs: 120_000,
     });
     if ((0, args_1.flagBool)(args, 'json')) {
@@ -251,11 +254,13 @@ async function dbMigrate(args) {
     const client = await (0, session_1.connectProject)(config.projectId, root, config);
     const migrations = requireMigrations(root);
     const dryRun = (0, args_1.flagBool)(args, 'dry-run');
+    const branch = (0, args_1.flagString)(args, 'branch');
     // Migrations live in the revisions of the project root: without this a project
     // without functions would lose them from its history, and a clone would miss them.
-    if (!dryRun)
+    // A try on a branch is not history yet.
+    if (!dryRun && !branch)
         await (0, sources_1.pushSources)({ kind: 'project', root, projectId: config.projectId }, client, { force: false });
-    await migrate(client, config.projectId, migrations, dryRun, (0, args_1.flagBool)(args, 'allow-destructive'));
+    await migrate(client, config.projectId, migrations, dryRun, (0, args_1.flagBool)(args, 'allow-destructive'), branch);
 }
 /** The functions deploy runs this first: new code must not meet an old schema. */
 async function migrateBeforeDeploy(client, root, projectId) {
@@ -271,14 +276,16 @@ async function migrateBeforeDeploy(client, root, projectId) {
         throw e;
     }
 }
-async function migrate(client, projectId, migrations, dryRun, allowDestructive) {
-    (0, ui_1.step)(dryRun ? `Checking the migrations (${migrations.length} in the directory)` : `Applying the migrations (${migrations.length} in the directory)`);
+async function migrate(client, projectId, migrations, dryRun, allowDestructive, branch) {
+    const where = branch ? ` to branch ${branch}` : '';
+    (0, ui_1.step)(dryRun ? `Checking the migrations${where} (${migrations.length} in the directory)` : `Applying the migrations${where} (${migrations.length} in the directory)`);
     const result = await (0, api_1.apiJson)(client, `/api/v1/projects/${projectId}/db/migrate`, {
         method: 'POST',
         body: {
             migrations,
             dry_run: dryRun,
             allow_destructive: allowDestructive,
+            branch,
         },
         timeoutMs: 300_000,
     });
@@ -314,3 +321,98 @@ async function migrate(client, projectId, migrations, dryRun, allowDestructive)
             : 'The database is unchanged: the migration rolled back as a whole');
     }
 }
+/** Time a branch has left, `5h` or `3d`. */
+function left(iso) {
+    const h = Math.max(0, Math.round((Date.parse(iso) - Date.now()) / 3_600_000));
+    return h < 48 ? `${h}h left` : `${Math.round(h / 24)}d left`;
+}
+/** Branches of the project database: list, create, delete. */
+async function dbBranch(args) {
+    const [sub, name] = args.words;
+    const { projectId, client } = await (0, session_1.projectTarget)(args);
+    const path = `/api/v1/projects/${projectId}/db/branches`;
+    if (sub === undefined || sub === 'list') {
+        const data = await (0, api_1.apiJson)(client, path);
+        if ((0, args_1.flagBool)(args, 'json')) {
+            (0, ui_1.out)(JSON.stringify(data, null, 2));
+            return;
+        }
+        if (data.branches.length === 0) {
+            (0, ui_1.note)('No branches');
+            (0, ui_1.note)((0, ui_1.dim)('  A copy to try things on: xflow db branch create <name> [--at 2h]'));
+            return;
+        }
+        (0, ui_1.table)(data.branches.map((b) => [b.name, b.at ? `as of ${new Date(b.at).toLocaleString()}` : 'as made', (0, ui_1.formatAge)(b.created_at), left(b.expires_at)]));
+        (0, ui_1.note)((0, ui_1.dim)(`  ${data.branches.length} of ${data.plan.branches}; a branch lives up to ${data.plan.ttl_hours / 24}d on this plan (xflow db branch extend <name>)`));
+        return;
+    }
+    if (!name)
+        throw new errors_1.CliError(`xflow db branch ${sub} needs a name`, `For example: xflow db branch ${sub} fix-orders`);
+    if (sub === 'create') {
+        const at = (0, args_1.flagString)(args, 'at');
+        const ttl = (0, args_1.flagString)(args, 'ttl');
+        const data = await (0, api_1.apiJson)(client, path, {
+            method: 'POST',
+            body: { name, at: at ? (0, moment_1.parseMoment)(at) : undefined, ttl_hours: ttl ? (0, moment_1.parseTtl)(ttl) : undefined },
+            timeoutMs: 180_000,
+        });
+        if ((0, args_1.flagBool)(args, 'json')) {
+            (0, ui_1.out)(JSON.stringify(data.branch, null, 2));
+            return;
+        }
+        (0, ui_1.ok)(`Branch ${name}: the project database ${data.branch.at ? `as of ${new Date(data.branch.at).toLocaleString()}` : 'as it is now'}`);
+        (0, ui_1.note)((0, ui_1.dim)(`  Work in it: xflow db query --branch ${name} '...', db exec and db migrate take --branch too`));
+        (0, ui_1.note)((0, ui_1.dim)(`  Rows back into the project database: xflow db restore --from ${name} --table <table>`));
+        (0, ui_1.note)((0, ui_1.dim)(`  Deleted on its own in ${left(data.branch.expires_at)}; more time: xflow db branch extend ${name}`));
+        return;
+    }
+    if (sub === 'extend') {
+        const ttl = (0, args_1.flagString)(args, 'ttl');
+        const data = await (0, api_1.apiJson)(client, `${path}/${encodeURIComponent(name)}`, {
+            method: 'PATCH',
+            body: { ttl_hours: ttl ? (0, moment_1.parseTtl)(ttl) : undefined },
+        });
+        if ((0, args_1.flagBool)(args, 'json')) {
+            (0, ui_1.out)(JSON.stringify(data.branch, null, 2));
+            return;
+        }
+        (0, ui_1.ok)(`Branch ${name}: ${left(data.branch.expires_at)}, until ${new Date(data.branch.expires_at).toLocaleString()}`);
+        return;
+    }
+    if (sub === 'delete' || sub === 'rm') {
+        await (0, api_1.apiJson)(client, `${path}/${encodeURIComponent(name)}`, { method: 'DELETE' });
+        (0, ui_1.ok)(`Branch ${name} deleted; the project database is unchanged`);
+        return;
+    }
+    throw new errors_1.CliError(`Unknown command: db branch ${sub}`, 'Available: list, create, extend and delete');
+}
+/** Rows of a table from a branch back into the project database, by primary key. */
+async function dbRestore(args) {
+    const from = (0, args_1.flagString)(args, 'from');
+    const tableName = (0, args_1.flagString)(args, 'table');
+    if (!from || !tableName) {
+        throw new errors_1.CliError('Name the branch and the table', "For example: xflow db restore --from before-import --table orders --where 'id in (7, 9)'");
+    }
+    const overwrite = (0, args_1.flagBool)(args, 'overwrite');
+    const { projectId, client } = await (0, session_1.projectTarget)(args);
+    const data = await (0, api_1.apiJson)(client, `/api/v1/projects/${projectId}/db/restore`, {
+        method: 'POST',
+        body: { branch: from, table: tableName, where: (0, args_1.flagString)(args, 'where'), overwrite },
+        timeoutMs: 120_000,
+    });
+    if ((0, args_1.flagBool)(args, 'json')) {
+        (0, ui_1.out)(JSON.stringify(data, null, 2));
+        return;
+    }
+    if (data.read === 0) {
+        (0, ui_1.note)(`No rows of ${tableName} in branch ${from} match`);
+        return;
+    }
+    (0, ui_1.ok)(`${data.restored} of ${data.read} rows of ${tableName} from branch ${from} ${overwrite ? 'written' : 'put back'}`);
+    for (const dump of data.dumps ?? []) {
+        (0, ui_1.note)((0, ui_1.dim)(`  Copy of ${dump.table} before the change: ${dump.rows} rows, kept for ${data.dump_retention_days} days`));
+    }
+    if (!overwrite && data.restored < data.read) {
+        (0, ui_1.note)((0, ui_1.dim)(`  The other ${data.read - data.restored} are in the database already and kept as they are: --overwrite replaces them`));
+    }
+}

package/dist/flags.js

@@ -78,10 +78,13 @@ exports.KNOWN = {
     'db status': ['project'],
     'db list': [],
     'db schema': ['project'],
-    'db query': ['json', 'project'],
-    'db exec': ['allow-destructive', 'json', 'project'],
+    'db query': ['json', 'project', 'branch'],
+    'db exec': ['allow-destructive', 'json', 'project', 'branch'],
     'db logs': ['limit', 'project', 'cursor'],
-    'db migrate': ['dry-run', 'allow-destructive'],
+    'db migrate': ['dry-run', 'allow-destructive', 'branch'],
+    'db branch': ['at', 'json', 'project', 'ttl'],
+    'db branches': ['at', 'json', 'project', 'ttl'],
+    'db restore': ['from', 'table', 'where', 'overwrite', 'json', 'project'],
     storage: ['json', 'project'],
     'storage ls': ['json', 'project'],
     'storage list': ['json', 'project'],

package/dist/help.js

@@ -98,6 +98,10 @@ ${(0, ui_1.bold)('Database')}
   xflow db logs                   errors the database raised, newest first
   xflow db migrate [--dry-run] [--allow-destructive]
                                   apply the migrations from migrations/*.sql
+  xflow db branch create <name> [--at 2h]
+                                  a copy of the database to try things on, now or as it was
+  xflow db restore --from <branch> --table <table>
+                                  put rows back from a branch, newer data kept
 
 ${(0, ui_1.bold)('Reference')}
   xflow logs [--limit N]          browser errors of the published apps
@@ -290,6 +294,14 @@ will work.`,
   xflow db logs                    errors the database raised: failed and timed-out queries
                                    with their SQL (cut to 2 KB), dropped connections; 7 days,
                                    1 on the Free plan (--limit, --cursor for older)
+  xflow db branch [list]           branches of the database (--json)
+  xflow db branch create <name>    a branch as the database is now; --at 2h, --at 14:05 or
+                                   --at 2026-10-30T14:05+03:00 for a moment of its history;
+                                   --ttl 12h or --ttl 3d to delete it sooner than the plan does
+  xflow db branch extend <name>    more time from now: the plan's longest, or --ttl
+  xflow db branch delete <name>    the branch goes, the database is unchanged
+  xflow db restore --from <branch> --table <table> [--where '...'] [--overwrite]
+                                   rows of a table from a branch back into the database
 
 Every project has exactly one database of its own, shared by all of its apps and functions,
 and every command here works from any folder of the project. ${(0, ui_1.bold)('list')} is about the
@@ -315,6 +327,23 @@ is saved; deleting also needs the right to destroy data on the key, as in migrat
 below). The rows it holds are locked while it runs, so a statement that waits on a running
 app is cancelled after a few seconds and changes nothing. There is no undo.
 
+${(0, ui_1.bold)('branch')}: a database of its own, as the project database is now or was at a moment of its
+history, made in seconds without copying: try a migration or a fix there (${(0, ui_1.bold)('--branch <name>')} on
+${(0, ui_1.bold)('query')}, ${(0, ui_1.bold)('exec')} and ${(0, ui_1.bold)('migrate')}), or read the data as it was. Nothing done there
+reaches the project database. A branch sleeps after a quiet minute, so its first query takes a
+second or two; it has no functions and no history of its own, and a branch of a branch is not
+made. Branches per project: 2 on Free, 5 on Start, 15 on Business; delete one you no longer need.
+A branch is deleted on its own when its lifetime ends: at most 1 day on Free, 7 days on Start,
+30 days on Business, and ${(0, ui_1.bold)('extend')} gives it more from now within that. The history reaches
+back 6 hours on Free, 3 days on Start, 7 days on Business.
+
+${(0, ui_1.bold)('restore')} puts rows back after a mistake without rolling the whole database back: make a
+branch as of a moment before it, check the rows there with ${(0, ui_1.bold)('query --branch')}, then restore
+them. Rows are told apart by the primary key: the missing ones go back in, the ones still there
+stay as they are, and ${(0, ui_1.bold)('--overwrite')} replaces them with the branch version (it needs the
+right to destroy data on the key). Everything the database got after that moment is kept. Up
+to 10 000 rows at a time: narrow with ${(0, ui_1.bold)('--where')}.
+
 ${(0, ui_1.bold)('migrate')}: the files live in the project root (${(0, ui_1.bold)('migrations/0001_init.sql')},
 ${(0, ui_1.bold)('migrations/0002_orders.sql')} and so on). The order comes from the file name, which
 is why the leading number is required. The command first stores the project root as a
@@ -325,13 +354,13 @@ itself, and anything already applied is not run again.
   --dry-run              report what would be applied without touching the database
   --allow-destructive    allow operations that destroy data
 
-About destructive ones. The platform keeps no database history and makes no backups,
-so ${(0, ui_1.bold)('DROP TABLE')}, ${(0, ui_1.bold)('DROP COLUMN')}, ${(0, ui_1.bold)('TRUNCATE')} and deleting rows (judged by what
+About destructive ones. ${(0, ui_1.bold)('DROP TABLE')}, ${(0, ui_1.bold)('DROP COLUMN')}, ${(0, ui_1.bold)('TRUNCATE')} and deleting rows (judged by what
 the database did, not by the text) need two things at once: this flag, and the right to destroy data on the
 access key. That right is off by default, and only its owner turns it on, in the
 platform settings, where the key permissions live: a flag is something an agent adds by itself, a
 right is not. With both in place, the contents of the affected tables are dumped and
-kept for 7 days: that is a "caught it right away" safety net, not a backup.
+kept for 7 days. Past that, a branch as of a moment before the migration holds the data
+while the history reaches that far (see ${(0, ui_1.bold)('branch')} above).
 ${(0, ui_1.bold)('DROP DATABASE')} is never allowed.
 
 Editing an already applied file achieves nothing: ${(0, ui_1.bold)('migrate')} refuses a name that is

package/dist/limits.js

@@ -15,6 +15,7 @@ const DENIAL_LABELS = {
     limit_seats: 'people in the organization',
     limit_schedule_interval: 'schedule frequency',
     limit_schedules: 'schedules in the organization',
+    limit_branches: 'database branches in the project',
     db_write_locked: 'database volume, writes are off',
     plan_no_schedules: 'schedules',
     subscription_blocked: 'the subscription is unpaid',
@@ -53,7 +54,7 @@ const QUOTA_LABELS = {
     people: 'People',
     space_mb: 'Space (databases and files together)',
     function_minutes: 'Function minutes',
-    db_hours: 'Database hours',
+    db_hours: 'Database GB-hours',
     builds: 'Builds this month',
 };
 /** Decimal units, 1000 MB per GB: matches how volumes are sold. */

package/dist/moment.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseMoment = parseMoment;
+exports.parseTtl = parseTtl;
+const errors_1 = require("./errors");
+const UNIT_MS = { m: 60_000, h: 3_600_000, d: 86_400_000 };
+/** `30m`/`2h`/`1d` ago, `14:05` local (yesterday if still ahead), or an ISO date. */
+function parseMoment(text, now = new Date()) {
+    const ago = /^(\d{1,4})([mhd])$/.exec(text);
+    if (ago)
+        return new Date(now.getTime() - Number(ago[1]) * UNIT_MS[ago[2]]).toISOString();
+    const clock = /^(\d{1,2}):(\d{2})$/.exec(text);
+    if (clock && Number(clock[1]) < 24 && Number(clock[2]) < 60) {
+        const at = new Date(now);
+        at.setHours(Number(clock[1]), Number(clock[2]), 0, 0);
+        if (at > now)
+            at.setDate(at.getDate() - 1);
+        return at.toISOString();
+    }
+    const at = new Date(text);
+    if (!/^\d{4}-\d{2}-\d{2}/.test(text) || Number.isNaN(at.getTime())) {
+        throw new errors_1.CliError(`--at ${text} is not a moment`, 'For example: --at 2h (two hours ago), --at 14:05 (today), --at 2026-10-30T14:05+03:00');
+    }
+    return at.toISOString();
+}
+/** A branch lifetime in whole hours: `12h` or `3d`. */
+function parseTtl(text) {
+    const m = /^(\d{1,4})([hd])$/.exec(text);
+    if (!m || Number(m[1]) < 1)
+        throw new errors_1.CliError(`--ttl ${text} is not a lifetime`, 'For example: --ttl 12h or --ttl 3d');
+    return Number(m[1]) * (m[2] === 'd' ? 24 : 1);
+}

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 = '1.8.1';
+exports.CLI_VERSION = '1.10.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,24 +1,24 @@
-{
-  "name": "@getxflow/cli",
-  "version": "1.8.1",
-  "description": "CLI for the XFlow platform: projects with apps, functions and a database; source sync, deployment and publishing",
-  "license": "UNLICENSED",
-  "engines": {
-    "node": ">=22"
-  },
-  "bin": {
-    "xflow": "dist/bin.js"
-  },
-  "files": [
-    "dist",
-    "skills"
-  ],
-  "scripts": {
-    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
-    "build": "npm run clean && tsc -p tsconfig.json",
-    "prepublishOnly": "npm run build"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@getxflow/cli",
+  "version": "1.10.0",
+  "description": "CLI for the XFlow platform: projects with apps, functions and a database; source sync, deployment and publishing",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "xflow": "dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}