@getxflow/cli 1.2.2 → 1.4.0

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.2';
+exports.CLI_VERSION = '1.4.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.2",
-  "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.4.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"
+  }
+}

package/skills/xflow/SKILL.md

@@ -12,7 +12,8 @@ address and runs its backend: one database and cloud functions per project.
 No `xflow.json` in the folder or above it means it is not bound to a project yet:
 `xflow projects list` names the projects of the organization with their ids, `xflow link <id>`
 binds the folder to one (an empty folder gets the whole project), and `xflow init` starts a new
-project with its first app.
+project with its first app. A person signed in to several organizations names the one that gets it:
+`xflow init <dir> --org <name>` (ask them which one if unsure; `xflow org` lists them).
 
 ## First rule
 
@@ -27,7 +28,7 @@ instead of guessing; give the person https://docs.getxflow.com when they ask how
 
 ## Keeping these instructions current
 
-These instructions ship with xflow CLI 1.2.2, so the copy you are reading can be older than
+These instructions ship with xflow CLI 1.4.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
@@ -62,8 +63,8 @@ the error points away from the cause. The sections below carry the details.
    name it already holds with different content. A schema change is always a new file.
 7. When `xflow db migrate` answers `db_write_locked`, or an INSERT or CREATE TABLE in a
    function fails with `permission denied` (42501), the database is over its plan size and
-   Postgres itself refuses. Reads, updates and deletes keep working, so the fix is a migration
-   that deletes data, never a rewrite of the SQL. Write comes back within the hour. The limit
+   Postgres itself refuses. Reads, updates and deletes keep working, so the fix is deleting data
+   (`xflow db exec` or a migration), never a rewrite of the SQL. Write comes back within the hour. The limit
    is shared by the organization: `xflow db list` shows the size of each project database.
 8. Heavy media does not travel with the sources. Photos, video and PDFs go up with
    `xflow storage push`, not into the repository: the archive is capped at 10 MB.
@@ -117,7 +118,7 @@ people in the organization, database and file storage, function minutes, builds
 (one count for all projects of the organization) and how often they may run, and which access levels an app may have. Most are finite; a plan
 may leave one uncapped, and then `whoami` prints `no limit` instead of a ceiling.
 `xflow whoami` prints every one of them next to what is used, and the rights of your own key
-with them: destroying data in a migration, deleting files from storage, moving a database and
+with them: destroying data (a migration or `db exec`), deleting files from storage, moving a database and
 linking a connected account each need a right. Reading it before a long task turns a refusal
 halfway through the work into a sentence said before it starts.
 
@@ -550,6 +551,12 @@ own `limit` asks, 50 without one, 300 at most; `--json` prints long values whole
 and zsh, cmd.exe wants double ones; a query with quotes of its own goes in a `.sql` file outside
 the project, `xflow db query ../q.sql`.
 
+A one-off data fix is `xflow db exec 'update ...'` (or `../fix.sql`), not a migration: one
+INSERT, UPDATE, DELETE or MERGE, saved at once, never re-run, no trace in the migration history.
+Schema changes are refused there. Deleting rows, or updating more than 100 in a table (cascades
+and triggers count), asks for `--allow-destructive`, and deleting also for the right below.
+There is no undo: read the rows with `db query` first.
+
 The platform keeps no database history and no backups, so anything that destroys data
 (`DROP TABLE`, `DROP COLUMN`, `TRUNCATE`, `DELETE`) needs both the `--allow-destructive` flag and
 the right to destroy data on the key, which is off by default and only its owner turns on. It is
@@ -582,8 +589,14 @@ An own server comes tuned and guarded, so do not tune it from migrations:
   scheduled function writing a summary table). A scheduled job that genuinely needs more runs
   `SET statement_timeout = '5min'` on its own connection. A database that used `citext` or
   another extension type cannot move back to `platform`.
-- A restart on a plan change 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.
+- A restart on a plan change takes about a minute.
+
+Calls of one project run at the same time in one process. A `Client`, even one made at module
+level, gets its own pooled connection for each call, so `connect()` twice is fine. Keep
+per-request data out of module-level variables. Session state (`SET` without `LOCAL`, temp tables,
+advisory locks) lasts until the call ends, and a transaction left open is rolled back: set what
+the call needs inside the handler. A `Client` that listens for `notification` keeps its own
+connection.
 
 ## File storage