@getxflow/cli 1.2.1 → 1.3.0

package/dist/bin.js

@@ -176,6 +176,10 @@ async function run(args) {
                 await (0, db_1.dbQuery)({ ...args, words: args.words.slice(2) });
                 return;
             }
+            if (second === 'exec') {
+                await (0, db_1.dbExec)({ ...args, words: args.words.slice(2) });
+                return;
+            }
             if (second === 'move') {
                 await (0, db_1.dbMove)(rest);
                 return;
@@ -184,7 +188,7 @@ async function run(args) {
                 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, migrate and move');
+            throw new errors_1.CliError(`Unknown command: db ${second}`, 'Available: status, list, schema, query, exec, migrate and move');
         case 'storage':
             if (second === 'push') {
                 await (0, storage_1.storagePush)(rest);

package/dist/commands/db.js

@@ -4,6 +4,7 @@ exports.dbStatus = dbStatus;
 exports.dbList = dbList;
 exports.dbSchema = dbSchema;
 exports.dbQuery = dbQuery;
+exports.dbExec = dbExec;
 exports.dbMove = dbMove;
 exports.dbMigrate = dbMigrate;
 exports.migrateBeforeDeploy = migrateBeforeDeploy;
@@ -227,6 +228,20 @@ async function dbSchema(args) {
     ]));
     (0, ui_1.note)((0, ui_1.dim)('  Columns of one table: xflow db schema <table>'));
 }
+/**
+ * The statement typed after the command, or read from the .sql file named there.
+ * The hint is split in lines: an agent terminal cuts a long one at its width.
+ */
+function readSql(words, command, example, file) {
+    const typed = words.join(' ').trim();
+    const sql = /\.sql$/i.test(typed)
+        ? (0, text_file_1.readTextFile)(typed, 'An argument ending in .sql is read as a file: check the path, or end the statement with ;')
+        : typed;
+    if (!sql) {
+        throw new errors_1.CliError(typed ? `${typed} is empty` : 'An SQL statement is required', `For example: xflow db ${command} '${example}'\n  A long one from a file outside the project: xflow db ${command} ../${file}`);
+    }
+    return sql;
+}
 /**
  * Reading data.
  *
@@ -234,14 +249,7 @@ async function dbSchema(args) {
  * database itself rather than by us guessing at the text of the SQL.
  */
 async function dbQuery(args) {
-    const typed = args.words.join(' ').trim();
-    const sql = /\.sql$/i.test(typed)
-        ? (0, text_file_1.readTextFile)(typed, 'An argument ending in .sql is read as a file: check the path, or end the query with ;')
-        : typed;
-    if (!sql) {
-        throw new errors_1.CliError(typed ? `${typed} is empty` : 'A query is required', "For example: xflow db query 'select * from orders order by created_at desc limit 20', " +
-            'or a long one from a file outside the project: xflow db query ../report.sql');
-    }
+    const sql = readSql(args.words, 'query', 'select * from orders order by created_at desc limit 20', 'report.sql');
     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',
@@ -280,6 +288,46 @@ async function dbQuery(args) {
             : `  Shown the first ${data.rows.length} rows, more exist: narrow the query, with a where clause or an offset`));
     }
 }
+/**
+ * A one-off data change: one INSERT, UPDATE, DELETE or MERGE, saved at once and
+ * kept out of the migration history. The platform judges it by what the database
+ * reports, not by the text: schema changes are refused, a mass change asks for
+ * --allow-destructive.
+ */
+async function dbExec(args) {
+    const sql = readSql(args.words, 'exec', "update orders set status = 'paid' where id = 42", 'fix.sql');
+    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') },
+        timeoutMs: 120_000,
+    });
+    if ((0, args_1.flagBool)(args, 'json')) {
+        (0, ui_1.out)(JSON.stringify(data, null, 2));
+        return;
+    }
+    // A write inside WITH comes tagged SELECT: its count is the rows read, the tables below say what changed.
+    (0, ui_1.ok)(data.command === 'SELECT'
+        ? 'The writes inside WITH are saved'
+        : `${data.command}: ${data.row_count} ${data.row_count === 1 ? 'row' : 'rows'}, saved`);
+    for (const t of data.tables) {
+        const parts = [
+            t.inserted > 0 ? `${t.inserted} inserted` : '',
+            t.updated > 0 ? `${t.updated} updated` : '',
+            t.deleted > 0 ? `${t.deleted} deleted` : '',
+        ].filter(Boolean);
+        (0, ui_1.note)((0, ui_1.dim)(`  ${t.table}: ${parts.join(', ')}`));
+    }
+    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 (data.rows.length > 0) {
+        (0, ui_1.out)('');
+        (0, ui_1.table)([data.columns, ...data.rows.map((row) => data.columns.map((column) => cell(row[column])))]);
+        if (data.truncated)
+            (0, ui_1.note)((0, ui_1.dim)(`  The first ${data.rows.length} returned rows: the rest are saved but not sent back`));
+    }
+}
 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;

package/dist/flags.js

@@ -79,6 +79,7 @@ exports.KNOWN = {
     'db list': [],
     'db schema': ['project'],
     'db query': ['json', 'project'],
+    'db exec': ['allow-destructive', 'json', 'project'],
     'db migrate': ['dry-run', 'allow-destructive'],
     'db move': ['to', 'yes', 'project'],
     storage: ['json', 'project'],

package/dist/help.js

@@ -94,6 +94,7 @@ ${(0, ui_1.bold)('Database')}
   xflow db list                   databases of the projects and the servers of the organization
   xflow db schema [table]         tables of the project, or the columns of one
   xflow db query 'select ...'     read data, in a read-only transaction
+  xflow db exec 'update ...'      a one-off data change, outside the migration history
   xflow db migrate [--dry-run] [--allow-destructive]
                                   apply the migrations from migrations/*.sql
   xflow db move --to <server> --yes
@@ -172,7 +173,7 @@ 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)('db move')}, ${(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 exec')}, ${(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')},
@@ -234,7 +235,7 @@ project, apps in subfolders:
 
 The root and every app are separate histories: apps/** never travels with the root, the
 root never travels with an app. The app is its appId, so a folder can be renamed freely.
-Who opens an app (members of the project, a list, anyone with the link) is set by a person
+Who opens an app (members of the project or anyone with the link) is set by a person
 in the web interface, not here.
 
 Both ${(0, ui_1.bold)('projects')} commands name the project positionally: the id is an argument, not a
@@ -341,6 +342,8 @@ will work.`,
   xflow db query 'select ...'      read data (rows: the query's own limit, 50 without
                                    one, 300 at most; --json prints the values whole)
   xflow db query <file>.sql        the same, the query read from a file
+  xflow db exec 'update ...'       a one-off data change: one INSERT, UPDATE, DELETE or MERGE
+                                   (or <file>.sql; --allow-destructive, --json)
   xflow db migrate                 store the project root, then apply migrations/*.sql
   xflow db move --to <server> --yes
                                    move the project database to another server
@@ -374,6 +377,15 @@ long values to keep the columns readable; ${(0, ui_1.bold)('--json')} prints the
 the applied limit and its ceiling. ${(0, ui_1.bold)('status')} named by id (${(0, ui_1.bold)('--project')}) answers with
 the applied history alone: comparing against ${(0, ui_1.bold)('migrations/')} needs the folder.
 
+${(0, ui_1.bold)('exec')} fixes data once: one INSERT, UPDATE, DELETE or MERGE, saved at once and kept out
+of the migration history, so a one-off fix no longer becomes a migration forever. Schema
+changes are refused: they stay with ${(0, ui_1.bold)('migrate')}. The platform judges the change by what the
+database reports, cascades and triggers included. Deleting rows, or updating more than 100
+in a table, asks for ${(0, ui_1.bold)('--allow-destructive')}, and those tables are copied for 7 days before it
+is saved; deleting also needs the right to destroy data on the key, as in migrations (see
+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)('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
@@ -385,8 +397,8 @@ itself, and anything already applied is not run again.
   --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 ${(0, ui_1.bold)('DELETE FROM')} without a
-condition need two things at once: this flag, and the right to destroy data on the
+so ${(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

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.2.1';
+exports.CLI_VERSION = '1.3.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.2.1",
-  "description": "CLI for the XFlow platform: projects with apps, functions and a database; source sync, deployment and publishing",
-  "license": "UNLICENSED",
-  "engines": {
-    "node": ">=20"
-  },
-  "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.3.0",
+  "description": "CLI for the XFlow platform: projects with apps, functions and a database; source sync, deployment and publishing",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=20"
+  },
+  "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"
+  }
+}