@getxflow/cli 0.4.0 → 0.5.0

package/README.md

@@ -21,6 +21,7 @@ else's code belongs next to it.
 | `status` / `push` / `pull` | state, sending and fetching sources |
 | `deploy` / `publish` / `rollback` / `deployments` | build, publish, roll back, version history |
 | `db status` / `db migrate` | migrations from `migrations/*.sql` with a gate on destructive ones |
+| `db schema` / `db query` | tables and columns, reading data in a read-only transaction |
 | `functions list` | cloud functions of the project from `functions/<name>/index.ts`, shipped by `deploy` |
 | `functions invoke` / `functions logs` | call a function, look at its crashes with the stack |
 | `schedules list` / `set` / `rm` | running functions on a timer (timer triggers) |

package/dist/api.js

@@ -14,7 +14,9 @@ class ApiError extends Error {
     issues;
     /** Set when a plan limit was hit. */
     limit;
-    constructor(message, code, status, hint, issues, limit) {
+    /** Cloud functions a build would delete, with code `confirm_required`. */
+    removing;
+    constructor(message, code, status, hint, issues, limit, removing) {
         super(message);
         this.name = 'ApiError';
         this.code = code;
@@ -22,6 +24,7 @@ class ApiError extends Error {
         this.hint = hint;
         this.issues = issues;
         this.limit = limit;
+        this.removing = removing;
     }
 }
 exports.ApiError = ApiError;
@@ -90,7 +93,7 @@ async function readError(response) {
     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.issues, parsed.limit);
+        return new ApiError(parsed.error || `Request rejected (${response.status})`, parsed.code || 'unknown', response.status, parsed.hint, parsed.issues, parsed.limit, parsed.removing);
     }
     catch {
         return new ApiError(`Request rejected (${response.status})`, 'unknown', response.status, text.slice(0, 200) || undefined);

package/dist/args.js

@@ -19,6 +19,7 @@ const BOOLEAN_FLAGS = new Set([
     'all',
     'dry-run',
     'allow-destructive',
+    'allow-removals',
     'show-token',
 ]);
 function parseArgs(argv) {

package/dist/bin.js

@@ -122,11 +122,19 @@ async function run(args) {
                 await (0, db_1.dbMigrate)(rest);
                 return;
             }
+            if (second === 'schema') {
+                await (0, db_1.dbSchema)({ ...args, words: args.words.slice(2) });
+                return;
+            }
+            if (second === 'query') {
+                await (0, db_1.dbQuery)({ ...args, words: args.words.slice(2) });
+                return;
+            }
             if (second === undefined || second === 'status') {
                 await (0, db_1.dbStatus)();
                 return;
             }
-            throw new errors_1.CliError(`Unknown command: db ${second}`, 'Available: status and migrate');
+            throw new errors_1.CliError(`Unknown command: db ${second}`, 'Available: status, schema, query and migrate');
         case 'status':
             await (0, sources_1.status)();
             return;

package/dist/commands/db.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.dbStatus = dbStatus;
+exports.dbSchema = dbSchema;
+exports.dbQuery = dbQuery;
 exports.dbMigrate = dbMigrate;
 const node_fs_1 = require("node:fs");
 const node_crypto_1 = require("node:crypto");
@@ -74,6 +76,84 @@ async function dbStatus() {
         (0, ui_1.warn)('A changed file will not be applied again: write a new migration');
     }
 }
+/** Long values would tear the columns apart; the cut is marked, never silent. */
+const CELL_LIMIT = 60;
+function cell(value) {
+    if (value === null || value === undefined)
+        return '-';
+    const text = typeof value === 'object' ? JSON.stringify(value) : String(value);
+    return text.length > CELL_LIMIT ? `${text.slice(0, CELL_LIMIT - 1)}…` : text;
+}
+/**
+ * What the database looks like right now.
+ *
+ * Not the same question as the migrations/ directory: one logical database is
+ * shared by several projects, so the files answer "what did I do", not "what is
+ * in there".
+ */
+async function dbSchema(args) {
+    const { config } = (0, config_1.requireProject)();
+    const client = (0, session_1.connect)(config);
+    const wanted = args.words[0];
+    const path = `/api/v1/projects/${config.projectId}/db/schema${wanted ? `?table=${encodeURIComponent(wanted)}` : ''}`;
+    if (wanted) {
+        const data = await (0, api_1.apiJson)(client, path);
+        (0, ui_1.out)(`${(0, ui_1.bold)(`${data.schema}.${data.table}`)}`);
+        (0, ui_1.out)('');
+        (0, ui_1.table)(data.columns.map((column) => [
+            column.column_name,
+            column.data_type,
+            column.is_nullable ? 'null' : 'not null',
+            [
+                column.is_primary_key ? 'primary key' : '',
+                column.is_foreign_key ? `→ ${column.foreign_key_ref ?? 'foreign key'}` : '',
+            ]
+                .filter(Boolean)
+                .join(' '),
+        ]));
+        return;
+    }
+    const data = await (0, api_1.apiJson)(client, path);
+    (0, ui_1.out)(`Schema: ${(0, ui_1.bold)(data.schema)}`);
+    (0, ui_1.out)('');
+    if (data.tables.length === 0) {
+        (0, ui_1.note)('No tables yet. The first migration: migrations/0001_init.sql');
+        return;
+    }
+    (0, ui_1.table)(data.tables.map((row) => [
+        row.table_name,
+        row.row_count === null ? '' : `~${row.row_count} rows`,
+        row.size ?? '',
+    ]));
+    (0, ui_1.note)((0, ui_1.dim)('  Columns of one table: xflow db schema <table>'));
+}
+/**
+ * Reading data.
+ *
+ * The query runs inside a READ ONLY transaction, so writes are rejected by the
+ * database itself rather than by us guessing at the text of the SQL.
+ */
+async function dbQuery(args) {
+    const { config } = (0, config_1.requireProject)();
+    const sql = args.words.join(' ').trim();
+    if (!sql) {
+        throw new errors_1.CliError('A query is required', 'For example: xflow db query "select * from orders order by created_at desc limit 20"');
+    }
+    const client = (0, session_1.connect)(config);
+    const data = await (0, api_1.apiJson)(client, `/api/v1/projects/${config.projectId}/db/query`, {
+        method: 'POST',
+        body: { sql, limit: (0, args_1.flagNumber)(args, 'limit') },
+        timeoutMs: 60_000,
+    });
+    if (data.rows.length === 0) {
+        (0, ui_1.note)('No rows');
+        return;
+    }
+    (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)(`  Shown ${data.rows.length} of ${data.total}: narrow the query or raise --limit`));
+    }
+}
 async function dbMigrate(args) {
     const { root, config } = (0, config_1.requireProject)();
     const client = (0, session_1.connect)(config);

package/dist/commands/deploy.js

@@ -10,6 +10,7 @@ const api_1 = require("../api");
 const args_1 = require("../args");
 const config_1 = require("../config");
 const errors_1 = require("../errors");
+const prompt_1 = require("../prompt");
 const session_1 = require("../session");
 const template_1 = require("../template");
 const ui_1 = require("../ui");
@@ -61,6 +62,44 @@ async function refreshFunctionsEnv(root, client, projectId) {
     }
     return card.functions.filter((fn) => fn.invoke_url).map((fn) => fn.name);
 }
+/**
+ * Start the build, asking before anything is destroyed.
+ *
+ * Removing a cloud function cannot be undone: one created again later gets a
+ * different address, and its schedules go with it. The platform therefore
+ * refuses such a build until the caller says yes, and the question is asked
+ * here, before the build starts, rather than reported once it already has.
+ */
+async function startBuild(client, projectId, revision, allowRemovals) {
+    const path = `/api/v1/projects/${projectId}/builds`;
+    try {
+        return await (0, api_1.apiJson)(client, path, {
+            method: 'POST',
+            body: { revision, allow_removals: allowRemovals },
+        });
+    }
+    catch (e) {
+        if (e instanceof api_1.ApiError && e.issues?.length)
+            reportIssues(e);
+        const removing = e instanceof api_1.ApiError && e.code === 'confirm_required' ? (e.removing ?? []) : [];
+        // No terminal (CI, an agent): the flag is the only way to say yes, and the
+        // platform message already names it.
+        if (removing.length === 0 || process.stdin.isTTY !== true || process.stderr.isTTY !== true)
+            throw e;
+        (0, ui_1.warn)(`Gone from the sources, the build would remove them: ${removing.join(', ')}`);
+        (0, ui_1.note)((0, ui_1.dim)('  Removal is final: a function created again later gets a different address, schedules included'));
+        const answer = await (0, prompt_1.select)('Remove them from the cloud?', [
+            { label: 'No, stop here', hint: 'bring the functions/<name>/index.ts directories back' },
+            { label: 'Yes, remove and build', hint: removing.join(', ') },
+        ]);
+        if (answer !== 1)
+            throw new errors_1.CliError('The build did not start', 'Nothing was removed');
+        return (0, api_1.apiJson)(client, path, {
+            method: 'POST',
+            body: { revision, allow_removals: true },
+        });
+    }
+}
 async function deploy(args) {
     const { root, config } = (0, config_1.requireProject)();
     const client = (0, session_1.connect)(config);
@@ -77,20 +116,7 @@ async function deploy(args) {
         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}`);
-    let started;
-    try {
-        started = await (0, api_1.apiJson)(client, `/api/v1/projects/${config.projectId}/builds`, {
-            method: 'POST',
-            body: { revision },
-        });
-    }
-    catch (e) {
-        if (e instanceof api_1.ApiError && e.issues?.length)
-            reportIssues(e);
-        throw e;
-    }
-    // Removing a function cannot be undone: a new one gets a new address. Say it
-    // out loud rather than leaving it to be discovered in functions list.
+    const started = await startBuild(client, config.projectId, revision, (0, args_1.flagBool)(args, 'allow-removals'));
     if (started.removed_functions?.length) {
         (0, ui_1.warn)(`Removed from the cloud, gone from the sources: ${started.removed_functions.join(', ')}`);
     }

package/dist/help.js

@@ -46,6 +46,8 @@ ${(0, ui_1.bold)('Functions')}
 
 ${(0, ui_1.bold)('Database')}
   xflow db status                 which migrations are applied and which are waiting
+  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 migrate [--dry-run] [--allow-destructive]
                                   apply the migrations from migrations/*.sql
 
@@ -63,22 +65,35 @@ ${(0, ui_1.bold)('Environment')}
 More about one command: xflow help <command>`);
 }
 const TOPICS = {
-    db: `${(0, ui_1.bold)('xflow db migrate')}: apply migrations
+    db: `${(0, ui_1.bold)('xflow db')}: schema, data, migrations
 
-The files live in the repository: ${(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. Every migration runs in its own transaction, the history is kept in the
-database itself, and anything already applied is not run again.
+  xflow db status                  what is applied and what is waiting
+  xflow db schema [table]          tables of the project, or the columns of one
+  xflow db query "select ..."      read data (--limit N)
+  xflow db migrate                 apply migrations/*.sql
+
+${(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
+says what is actually in there. ${(0, ui_1.bold)('query')} runs inside a READ ONLY transaction, so
+writes are rejected by the database itself, not by us reading your SQL.
+
+${(0, ui_1.bold)('migrate')}: the files live in the repository (${(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. Every migration runs in its own transaction, the
+history is kept in the database 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 ${(0, ui_1.bold)('DELETE FROM')} without a
-condition are rejected unless the flag is given. With the flag, 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. ${(0, ui_1.bold)('DROP DATABASE')} is never allowed, because the database
-is shared across the organization.
+condition 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 under Developers: 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.
+${(0, ui_1.bold)('DROP DATABASE')} is never allowed, because the database is shared across the
+organization.
 
 Editing an already applied file achieves nothing: the comparison is by name, not by
 content. ${(0, ui_1.bold)('xflow db status')} lists such a file separately, so write a new migration
@@ -233,8 +248,9 @@ Three steps: sending the sources, shipping the cloud functions, building the app
 The build command and the output directory come from xflow.json (npm run build and dist
 by default).
 
-  --no-push       do not send sources, build from the latest server revision
-  --force         allow overwriting the server revision while sending
+  --no-push          do not send sources, build from the latest server revision
+  --force            allow overwriting the server revision while sending
+  --allow-removals   agree in advance to remove the functions gone from the sources
 
 The platform builds, in a clean sandbox on one Node version for everybody, so "it
 worked on my machine" no longer depends on your machine. Before the build the project
@@ -247,10 +263,12 @@ works: the addresses of the functions are baked into the bundle, so they have to
 first. A function whose code and variables did not change is left alone, and a function
 that fails to ship fails the whole build.
 
-A function gone from the sources is deleted from the cloud along with its schedules, and
-the CLI names it before the build starts. That one is final: a function created again
-later gets a different address. If the sources hold no functions at all while the cloud
-holds several, nothing is deleted: that looks like a directory which never made it (a
+A function gone from the sources would be deleted from the cloud along with its
+schedules, and that is final: one created again later gets a different address. So the
+build does not start at all until you say yes. In a terminal the CLI names the functions
+and asks; without one (CI, an agent) it stops and ${(0, ui_1.bold)('--allow-removals')} is the only way
+to agree. If the sources hold no functions at all while the cloud holds several, nothing
+is deleted and nothing is asked: that looks like a directory which never made it (a
 ${(0, ui_1.bold)('functions/')} line in .xflowignore) rather than a decision.
 
 The database is not part of this: migrations change data in ways nothing can undo, so

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

package/skills/xflow/SKILL.md

@@ -68,7 +68,9 @@ restored within an hour of the data going back under the limit.
 6. `xflow publish` makes that same version visible to visitors.
 
 The split is deliberate: shipping a build and showing it are two separate decisions.
-Until `publish` runs, visitors keep seeing the previous version.
+Until `publish` runs, visitors keep seeing the previous version. The one exception is
+the very first version of a project: it publishes automatically, since there is no
+live version to protect yet.
 
 Rolling back: `xflow deployments` lists the version history, `xflow rollback <id>`
 points the project back at an earlier build. Sources stay on their own revision.
@@ -162,10 +164,17 @@ on every call. Branch the frontend on `error.code`, never on `error.message`: wo
 gets rewritten on any edit, a code does not.
 
 The sources are the whole truth about which functions exist. Delete the directory and the
-next deploy deletes the function from the cloud, schedules included, and that cannot be
+next deploy would delete the function from the cloud, schedules included, and that cannot be
 undone: a function created again later gets a different address. So never remove a function
 directory to "clean up" unless the user asked for the function to go.
 
+Such a deploy does not start on its own: the platform names the functions it would remove and
+refuses until somebody agrees. Under an agent there is no terminal to ask in, so the refusal
+reaches you, and `--allow-removals` is the only way past it. Adding that flag to get the
+build running is exactly the wrong move: it means you deleted something the user did not ask
+you to delete. Put the directories back instead, and if the removal really is intended, say
+which functions are about to go and let the user answer.
+
 Debugging a deployed function is two commands: `xflow functions invoke <name>` calls it
 the way the app does and prints status, timing and body (`--data '{"a":1}'` sends a body),
 and `xflow functions logs <name>` shows the failures, each with its stack and the console
@@ -276,13 +285,23 @@ under one of them would shadow the real one.
 
 The platform keeps no database history and no backups. Anything that destroys data
 (`DROP TABLE`, `DROP COLUMN`, `TRUNCATE`, `DELETE FROM` without a condition) is refused
-unless you pass `--allow-destructive`, and with that flag the affected tables are dumped
-first and kept for 7 days. Check with `--dry-run` before applying.
+unless two things hold at once: you pass `--allow-destructive`, and the access key carries
+the right to destroy data. That right is off by default and only its owner can turn it on,
+in the platform settings, under Developers. So when a destructive migration is refused for
+the right rather than the flag, adding the flag changes nothing: say what needs deleting and
+why, and let the person decide. With both in place the affected tables are dumped first and
+kept for 7 days. Check with `--dry-run` before applying.
 
 One logical database can be shared by several projects, so your migration can break an app
 you do not see. `xflow db status` lists applied migrations that have no file in your
 repository: that is what someone else's project did.
 
+For the same reason the `migrations/` directory is not the schema. It says what you did;
+`xflow db schema` says what is in the database right now, and `xflow db schema <table>` gives
+the columns of one table. `xflow db query "select ..."` reads data, inside a READ ONLY
+transaction, so a write there fails by design rather than by accident. Look before you write
+a migration against a shared database.
+
 ## File storage
 
 The project has file storage, and the browser cannot reach it. Those endpoints take only the
@@ -356,12 +375,11 @@ read-only queries, migrations, function logs and invocations, schedules, environ
 variables, versions, publish and rollback. They answer with aggregates and say explicitly
 when a result is truncated, which parsing terminal output does not.
 
-Code never travels through those tools. Sending sources stays in the CLI (`xflow push`):
-pulling a repository through tool calls burns the user's tokens for nothing. Building is
-available through the tools, because it runs from the revision already stored on the
-server: `deployments action=build` starts it and answers immediately, `action=status`
-reports the phase. It ships the functions too, from that same revision. A build takes
-minutes, so never expect the starting call to return a finished version.
+Anything that depends on the working copy stays in the CLI: sending sources (`xflow push`),
+building and shipping the functions (`xflow deploy`), creating a project (`xflow init`). The
+tools cannot see the folder you are working in, so a build started from there would release
+whatever revision the server happens to hold, not what you have on disk. Pulling a repository
+through tool calls also burns the user's tokens for nothing.
 
 ## Do not