@getxflow/cli 0.11.1 → 0.12.0

package/dist/api.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ApiError = void 0;
+exports.isOlder = isOlder;
 exports.newerVersionSeen = newerVersionSeen;
 exports.apiJson = apiJson;
 exports.apiBinary = apiBinary;

package/dist/bin.js

@@ -170,7 +170,7 @@ async function run(args) {
                 return;
             }
             if (second === undefined || second === 'status') {
-                await (0, db_1.dbStatus)();
+                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');
@@ -227,13 +227,15 @@ function nudge() {
 }
 /**
  * The other staleness, and the one that costs more: the instructions an agent reads are
- * older than the CLI answering it, and nothing about that is visible in the text. Louder
- * than the notice above because it is wrong now rather than out of date soon, and it names
- * the file, because a machine can hold a dozen copies and the wrong one gets edited.
+ * not the ones the CLI answering it ships, and nothing about that is visible in the text.
+ * Louder than the notice above because it is wrong now rather than out of date soon, and
+ * it names the file, because a machine can hold a dozen copies and the wrong one gets edited.
  *
  * The command is skills --refresh, not update: what is out of step here is the copies, not
  * the package, and refreshing needs no network, no npm and no rights on a global folder.
- * The re-read is half the repair, so it is in the same breath as the command.
+ * The re-read is half the repair, so it is in the same breath as the command. Except when
+ * a newer CLI is known: then the package itself is behind, a refresh would rewrite the
+ * copies from it, and the update notice above is the whole advice.
  */
 function nudgeSkill() {
     const stale = (0, skills_1.staleSkillCopy)(process.cwd());
@@ -243,10 +245,17 @@ function nudgeSkill() {
         (0, state_1.clearSkillNudges)();
         return;
     }
+    // A newer CLI is published: the copy that differs may well be ahead of this package,
+    // and a refresh would "repair" it backwards. The update notice is the whole advice —
+    // xflow update brings the package and every copy along. Network-free commands see no
+    // headers, so the version an earlier notice named counts as known too.
+    const nudged = (0, state_1.lastNudgedVersion)();
+    if ((0, api_1.newerVersionSeen)() !== null || (nudged !== null && (0, api_1.isOlder)(version_1.CLI_VERSION, nudged)))
+        return;
     const key = `${stale} ${version_1.CLI_VERSION}`;
     if (!(0, state_1.shouldNudgeSkill)(key))
         return;
-    (0, ui_1.warn)(`${stale} is older than this CLI`);
+    (0, ui_1.warn)(`${stale} does not match this CLI`);
     (0, ui_1.note)((0, ui_1.dim)('  Run xflow skills --refresh, then read that file again: the refresh only writes it to disk'));
     (0, state_1.markSkillNudged)(key);
 }
@@ -304,8 +313,8 @@ async function main() {
         if (!quiet)
             nudge();
         // Not behind the same flag: a copy out of step with the running package stays wrong
-        // whatever the command was, and when the package itself is the problem the copies
-        // match it and this says nothing anyway.
+        // whatever the command was, and when the package itself is the problem this steps
+        // aside on its own.
         nudgeSkill();
     }
 }

package/dist/commands/db.js

@@ -39,7 +39,22 @@ function requireMigrations(root) {
     }
     return migrations;
 }
-async function dbStatus() {
+async function dbStatus(args) {
+    // Named by id there is no migrations/ directory to compare against: the answer
+    // 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 history = await (0, api_1.apiJson)(client, `/api/v1/projects/${projectId}/db/migrate`);
+        (0, ui_1.out)(`Schema: ${(0, ui_1.bold)(history.schema)}`);
+        (0, ui_1.out)('');
+        if (history.applied.length === 0) {
+            (0, ui_1.note)('No migrations have been applied yet');
+            return;
+        }
+        (0, ui_1.table)(history.applied.map((row) => [row.name, (0, ui_1.formatAge)(row.applied_at)]));
+        (0, ui_1.note)((0, ui_1.dim)('  Applied history only: comparing against migrations/ needs the project folder'));
+        return;
+    }
     const { root, config } = (0, config_1.requireProject)();
     const client = (0, session_1.connect)(config);
     const local = readMigrations(root);
@@ -106,10 +121,13 @@ async function dbList() {
 }
 /** Long values would tear the columns apart; the cut is marked, never silent. */
 const CELL_LIMIT = 60;
-function cell(value) {
+function plain(value) {
     if (value === null || value === undefined)
         return '-';
-    const text = typeof value === 'object' ? JSON.stringify(value) : String(value);
+    return typeof value === 'object' ? JSON.stringify(value) : String(value);
+}
+function cell(value) {
+    const text = plain(value);
     return text.length > CELL_LIMIT ? `${text.slice(0, CELL_LIMIT - 1)}…` : text;
 }
 /**
@@ -171,11 +189,28 @@ async function dbQuery(args) {
         body: { sql, limit: (0, args_1.flagNumber)(args, 'limit') },
         timeoutMs: 60_000,
     });
+    // The whole values, machine-readable, on stdout alone: the notes go to stderr.
+    if ((0, args_1.flagBool)(args, 'json')) {
+        (0, ui_1.out)(JSON.stringify({
+            schema: data.schema,
+            columns: data.columns,
+            rows: data.rows,
+            truncated: data.truncated,
+            limit: data.limit,
+            limit_max: data.limit_max,
+        }, null, 2));
+        return;
+    }
     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])))]);
+    // Two different cuts, named apart: this one is about the width of a cell, the
+    // one below is about the number of rows.
+    if (data.rows.some((row) => data.columns.some((column) => plain(row[column]).length > CELL_LIMIT))) {
+        (0, ui_1.note)((0, ui_1.dim)(`  Values longer than ${CELL_LIMIT} characters are cut to keep the columns readable: --json prints them whole`));
+    }
     if (data.truncated) {
         // No exact total here: the platform stops reading at limit + 1 rows, so all
         // it knows is that more exist. The "raise --limit" advice shows only while

package/dist/commands/projects.js

@@ -10,6 +10,7 @@ const node_path_1 = require("node:path");
 const api_1 = require("../api");
 const args_1 = require("../args");
 const config_1 = require("../config");
+const credentials_1 = require("../credentials");
 const errors_1 = require("../errors");
 const session_1 = require("../session");
 const skills_1 = require("./skills");
@@ -123,6 +124,9 @@ async function link(args) {
     if (!projectId) {
         throw new errors_1.CliError('A project identifier is required', 'The list: xflow projects list');
     }
+    if (!(0, session_1.isProjectId)(projectId)) {
+        throw new errors_1.CliError(`link takes a project id, got "${projectId}"`, 'The ids: xflow projects list');
+    }
     let card;
     try {
         card = await (0, api_1.apiJson)(client, `/api/v1/projects/${projectId}`);
@@ -192,25 +196,44 @@ async function list() {
     const root = (0, config_1.findProjectRoot)();
     const client = (0, session_1.connect)(root ? (0, config_1.readConfig)(root) : undefined);
     const { projects } = await (0, api_1.apiJson)(client, '/api/v1/projects');
-    if (projects.length === 0) {
+    if (projects.length > 0) {
+        (0, ui_1.table)(projects.map((p) => [
+            p.id,
+            p.name,
+            p.live_deploy_id ? 'published' : p.dev_deploy_id ? 'dev only' : 'no build',
+            (0, ui_1.formatAge)(p.updated_at),
+        ]));
+    }
+    else {
         (0, ui_1.note)('No projects. To create one: xflow init');
-        return;
     }
-    (0, ui_1.table)(projects.map((p) => [
-        p.id,
-        p.name,
-        p.live_deploy_id ? 'published' : p.dev_deploy_id ? 'dev only' : 'no build',
-        (0, ui_1.formatAge)(p.updated_at),
-    ]));
+    // One organization answers, and with several signed in that is worth saying:
+    // a project that "is not here" may simply live in another one. Not under an
+    // env key or a folder binding, where "active" would be the wrong word.
+    const orgs = (0, credentials_1.listOrgs)(client.apiUrl);
+    if (client.source === 'active' && orgs.length > 1) {
+        const name = orgs.find((org) => org.active)?.name;
+        (0, ui_1.note)((0, ui_1.dim)(`  Projects of ${name ? `"${name}"` : 'the active organization'} alone: the rest of xflow org answer after org switch`));
+    }
 }
 async function get(args) {
     const root = (0, config_1.findProjectRoot)();
     const config = root ? (0, config_1.readConfig)(root) : undefined;
-    const projectId = args.words[0] ?? config?.projectId;
+    const explicit = args.words[0];
+    if (explicit !== undefined && !(0, session_1.isProjectId)(explicit)) {
+        throw new errors_1.CliError(`projects get takes a project id, got "${explicit}"`, 'The ids: xflow projects list');
+    }
+    const projectId = explicit ?? config?.projectId;
     if (!projectId) {
         throw new errors_1.CliError('A project identifier is required', 'Or run the command inside the project folder');
     }
-    const client = (0, session_1.connect)(config);
+    // An id typed by hand is looked for across every signed-in organization and
+    // ignores the folder whole, xflow.json included, the way --project does it.
+    // Named by the folder, the project of an unbound one gets probed and the
+    // binding written, the way publish and pull do it.
+    const client = explicit !== undefined
+        ? await (0, session_1.connectProject)(explicit, null)
+        : await (0, session_1.connectProject)(projectId, root, config);
     const card = await (0, api_1.apiJson)(client, `/api/v1/projects/${projectId}`);
     (0, ui_1.out)(`${(0, ui_1.bold)(card.name)}  ${(0, ui_1.dim)(card.id)}`);
     if (card.description)

package/dist/flags.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.KNOWN = void 0;
 exports.checkFlags = checkFlags;
 const args_1 = require("./args");
 const errors_1 = require("./errors");
@@ -17,11 +18,17 @@ const help_1 = require("./help");
  * whoever is at the keyboard gets the flags of this very command back.
  *
  * `--project` is a flag like any other here, and it is written against a command
- * only when that command does not read the working copy. The ones that do (deploy,
- * pull, status, db migrate, db status, env check, env set, connections unlink) have
+ * only when that command can answer without the working copy. The ones that cannot
+ * (deploy, pull, status, db migrate, env check, env set, connections unlink) have
  * a folder to stand in, and naming a project they cannot read would be a lie.
+ * `db status` sits halfway: named by id it answers with the applied history alone,
+ * without the comparison against migrations/.
+ *
+ * flags-sync.test.ts holds this table against the code: a flag listed here has to
+ * be read by the handler of its command, and a flag the handler reads has to be
+ * listed here. A new command or a new way of reading flags shows up there first.
  */
-const KNOWN = {
+exports.KNOWN = {
     help: [],
     login: [],
     logout: ['all'],
@@ -59,11 +66,11 @@ const KNOWN = {
     'schedules set': ['payload', 'payload-file', 'project'],
     'schedules rm': ['project'],
     'schedules remove': ['project'],
-    db: [],
-    'db status': [],
+    db: ['project'],
+    'db status': ['project'],
     'db list': [],
     'db schema': ['project'],
-    'db query': ['limit', 'project'],
+    'db query': ['limit', 'json', 'project'],
     'db migrate': ['dry-run', 'allow-destructive'],
     storage: ['json', 'project'],
     'storage ls': ['json', 'project'],
@@ -103,18 +110,18 @@ function commandOf(words) {
     if (!first)
         return null;
     if (second !== undefined) {
-        if (Object.hasOwn(KNOWN, `${first} ${second}`))
+        if (Object.hasOwn(exports.KNOWN, `${first} ${second}`))
             return `${first} ${second}`;
         if (NAMESPACES.has(first))
             return null;
     }
-    return Object.hasOwn(KNOWN, first) ? first : null;
+    return Object.hasOwn(exports.KNOWN, first) ? first : null;
 }
 function checkFlags(args) {
     const command = commandOf(args.words);
     if (command === null)
         return;
-    const allowed = KNOWN[command];
+    const allowed = exports.KNOWN[command];
     const topic = command.split(' ')[0];
     // Not every command has a page, and sending the reader to "No page for login"
     // would be a second dead end in the same breath as the first.

package/dist/help.js

@@ -101,8 +101,8 @@ ${(0, ui_1.bold)('Reference')}
   xflow --version                 which version is installed
 
 ${(0, ui_1.bold)('Outside a project folder')}
-  --project <id>                  name the project by id, for every command that does
-                                  not read the local files (xflow help project)
+  --project <id>                  name the project by id, for every command that can
+                                  answer without the local files (xflow help project)
 
 ${(0, ui_1.bold)('Environment')}
   XFLOW_TOKEN                     access key (for CI, instead of xflow login)
@@ -152,21 +152,26 @@ 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 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)('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)('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')}.
+${(0, ui_1.bold)('deployments')}, ${(0, ui_1.bold)('publish')}, ${(0, ui_1.bold)('rollback')}. ${(0, ui_1.bold)('db status')} answers with less
+under the flag: the applied history alone, because comparing it against the local
+${(0, ui_1.bold)('migrations/')} directory needs the folder.
 
-The rest read 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)('db migrate')}, ${(0, ui_1.bold)('db status')},
-${(0, ui_1.bold)('env check')}, ${(0, ui_1.bold)('env set')}, ${(0, ui_1.bold)('connections unlink')}. They answer about the files
-next to them, so they keep asking for a folder.
+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)('db migrate')}, ${(0, ui_1.bold)('env check')},
+${(0, ui_1.bold)('env set')}, ${(0, ui_1.bold)('connections unlink')}. 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.
 
 The folder is then ignored whole, and that includes its ${(0, ui_1.bold)('xflow.json')}: the address
 is app.getxflow.com, or ${(0, ui_1.bold)('XFLOW_API_URL')} when it is set, and never the ${(0, ui_1.bold)('api')} field
 of a config that happens to be lying around. Standing in the folder of a self-hosted
-project, the flag therefore goes somewhere else than the folder does.
+project, the flag therefore goes somewhere else than the folder does. An id handed to
+${(0, ui_1.bold)('projects get')} or ${(0, ui_1.bold)('link')} behaves the same way: typed by hand, it is not redirected
+by a config lying around either.
 
 The id is echoed back on every run. It is the one place a project is named by hand,
 and a wrong id answers "not found" on a read but works on a write.
@@ -175,6 +180,24 @@ With several organizations signed in, the one holding the project is looked for
 every call: there is no folder to write the answer into, and a second place to
 remember it would be a second thing to keep true. One ${(0, ui_1.bold)('xflow org switch')} to the
 right organization spares that search.`,
+    projects: `${(0, ui_1.bold)('xflow projects')}: the projects of the organization
+
+  xflow projects list             every project, its versions state and age
+  xflow projects get [id]         one card: versions, database, functions, schedules
+
+Both name the project positionally: the id is an argument, not a --project flag.
+Without one, ${(0, ui_1.bold)('get')} answers about the project of the folder it stands in.
+
+An id typed by hand is looked for across every signed-in organization, and the
+folder around the command is ignored whole, the way the ${(0, ui_1.bold)('--project')} flag does it
+(${(0, ui_1.bold)('xflow help project')}). So "not found" means the id is wrong, or its organization
+is missing from ${(0, ui_1.bold)('xflow org')}: never that the active key was simply the wrong one.
+
+${(0, ui_1.bold)('list')} stays within one organization: the bound one inside a project folder, the
+active one outside. With several signed in, a line under the table says whose
+projects these are.
+
+${(0, ui_1.bold)('xflow link <id>')} binds the current folder to a project; ${(0, ui_1.bold)('xflow init')} makes a new one.`,
     update: `${(0, ui_1.bold)('xflow update')}: bring the CLI up to date
 
 Installs the published version and, if anything changed, rewrites the platform
@@ -203,7 +226,8 @@ will work.`,
   xflow db status                  what is applied and what is waiting
   xflow db list                    databases of the organization, and who is on them
   xflow db schema [table]          tables of the project, or the columns of one
-  xflow db query "select ..."      read data (--limit N: 50 by default, 300 at most)
+  xflow db query "select ..."      read data (--limit N: 50 by default, 300 at most;
+                                   --json prints the values whole)
   xflow db migrate                 apply migrations/*.sql
 
 ${(0, ui_1.bold)('list')} is about the organization, not about this project: it names the logical
@@ -213,7 +237,10 @@ attached to each one. That last column is the one to read before a migration.
 ${(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.
+writes are rejected by the database itself, not by us reading your SQL. Its table cuts
+long values to keep the columns readable; ${(0, ui_1.bold)('--json')} prints them whole, together with
+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)('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

package/dist/state.js

@@ -5,6 +5,7 @@ exports.shouldNudgeSkill = shouldNudgeSkill;
 exports.markSkillNudged = markSkillNudged;
 exports.clearSkillNudges = clearSkillNudges;
 exports.markNudged = markNudged;
+exports.lastNudgedVersion = lastNudgedVersion;
 const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
@@ -78,6 +79,10 @@ function clearSkillNudges() {
 function markNudged(version) {
     write({ nudgedVersion: version, nudgedAt: new Date().toISOString() });
 }
+/** What the update notice last named, for callers that outlive the process that saw it. */
+function lastNudgedVersion() {
+    return read().nudgedVersion ?? null;
+}
 /** Best effort: a read-only home folder must not break the command that just worked. */
 function write(patch) {
     try {

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

package/skills/xflow/SKILL.md

@@ -24,11 +24,11 @@ contains the fix.
 
 ## Keeping these instructions current
 
-These instructions ship with xflow CLI 0.11.1. They travel inside the package, so the copy
+These instructions ship with xflow CLI 0.12.0. They travel inside the package, so the copy
 you are reading can be older than the CLI answering your commands, and nothing about that
 is visible in the text itself.
 
-When the CLI says this file is out of date, run `xflow skills --refresh` and then **read
+When the CLI says this file does not match it, run `xflow skills --refresh` and then **read
 again the file it names**. Refreshing only writes new text to disk; until you re-read it you
 are still working from the old rules, and the command will look like it did nothing. This
 repair is yours to make, no need to ask anyone.
@@ -424,7 +424,8 @@ organization and the projects on each, which is where you find out who else is o
 For the same reason `migrations/` is not the
 schema. It says what you did; `xflow db schema [table]` says what is in the database right
 now, and `xflow db query "select ..."` reads it inside a READ ONLY transaction (50 rows by
-default, `--limit` raises that to 300). Look before
+default, `--limit` raises that to 300). The table cuts long values to keep the columns
+readable; `--json` prints them whole. Look before
 you write a migration against a shared database.
 
 ## File storage
@@ -525,8 +526,9 @@ One key per organization, stored side by side rather than replacing each other:
 Inside a project folder there is nothing to switch: commands follow the organization the
 folder is bound to, whatever the active one is. That is what lets two projects of two
 organizations work side by side. The exception is `--project <id>`, which every command
-that does not read the working copy takes (`xflow help project` lists them): it ignores the
-folder whole, so a second project needs no second checkout.
+that can answer without the working copy takes (`xflow help project` lists them): it ignores
+the folder whole, so a second project needs no second checkout. `projects get` and `link`
+take no flag and name the project by its id as an argument instead.
 
 A "not found" on a project you know exists usually means the key belongs to another
 organization, not that the project is gone: ids are unique across the platform, so a