@getxflow/cli 0.3.3 → 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

@@ -60,7 +60,7 @@ async function run(args) {
             }
             throw new errors_1.CliError(`Unknown command: projects ${second}`, 'Available: list and get');
         case 'skills':
-            (0, skills_1.skills)(rest);
+            await (0, skills_1.skills)(rest);
             return;
         case 'mcp':
             if (second === undefined || second === 'install') {
@@ -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/commands/skills.js

@@ -7,18 +7,22 @@ const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const args_1 = require("../args");
 const errors_1 = require("../errors");
+const prompt_1 = require("../prompt");
 const ui_1 = require("../ui");
-/**
- * The SKILL.md format is shared across tools (agentskills.io); each agent reads
- * its own folder. Cursor reads .cursor/rules/*.mdc instead, so it gets the same
- * text under its own header.
- */
-const SKILL_DIRS = [
-    ['.claude', 'skills'],
-    ['.agents', 'skills'],
+const AGENTS = [
+    { id: 'claude', label: 'Claude Code', project: ['.claude', 'skills'], global: ['.claude', 'skills'] },
+    { id: 'cursor', label: 'Cursor', project: ['.agents', 'skills'], global: ['.cursor', 'skills'], rule: true },
+    { id: 'codex', label: 'Codex', project: ['.agents', 'skills'], global: ['.codex', 'skills'] },
+    { id: 'copilot', label: 'GitHub Copilot', project: ['.agents', 'skills'], global: ['.copilot', 'skills'] },
+    { id: 'gemini', label: 'Gemini CLI', project: ['.agents', 'skills'], global: ['.gemini', 'skills'] },
+    { id: 'opencode', label: 'OpenCode', project: ['.agents', 'skills'], global: ['.config', 'opencode', 'skills'] },
+    { id: 'windsurf', label: 'Windsurf', project: ['.windsurf', 'skills'], global: ['.codeium', 'windsurf', 'skills'] },
+    { id: 'openclaw', label: 'OpenClaw', project: ['skills'], global: ['.openclaw', 'skills'] },
+    { id: 'universal', label: 'Other agents (Cline, Warp, Zed, Amp)', project: ['.agents', 'skills'], global: ['.agents', 'skills'] },
 ];
-/** Codex reads its global skills from .codex/skills, not from .agents. */
-const GLOBAL_SKILL_DIRS = [...SKILL_DIRS, ['.codex', 'skills']];
+/** What init and link lay down, and what a run without questions refreshes. */
+const DEFAULT_PROJECT = ['claude', 'cursor', 'codex'];
+const DEFAULT_GLOBAL = ['claude', 'codex', 'universal'];
 const CURSOR_RULE = ['.cursor', 'rules', 'xflow.mdc'];
 /** AGENTS.md is always read, unlike the lazily loaded skill: a short pointer lives there. */
 const POINTER_MARKER = '<!-- xflow-skill -->';
@@ -44,14 +48,20 @@ function cursorRule(skill) {
     const body = skill.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '');
     return `---\ndescription: ${description}\nalwaysApply: false\n---\n\n${body}`;
 }
-/** Writes only when the content differs. Returns the touched path. */
+function skillPath(base, agent, global) {
+    return (0, node_path_1.join)(global ? (0, node_os_1.homedir)() : base, ...(global ? agent.global : agent.project), 'xflow', 'SKILL.md');
+}
+function installed(base, agent, global) {
+    return (0, node_fs_1.existsSync)(skillPath(base, agent, global));
+}
+/** Writes only when the content differs. */
 function writeIfChanged(path, content) {
     const before = (0, node_fs_1.existsSync)(path) ? (0, node_fs_1.readFileSync)(path, 'utf-8') : null;
     if (before === content)
         return null;
     (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
     (0, node_fs_1.writeFileSync)(path, content, 'utf-8');
-    return path;
+    return before === null ? 'new' : 'updated';
 }
 /** Append once, by marker: the file belongs to the user. */
 function appendPointer(base) {
@@ -60,31 +70,48 @@ function appendPointer(base) {
     if (before?.includes(POINTER_MARKER))
         return null;
     (0, node_fs_1.writeFileSync)(path, before ? `${before.replace(/\s*$/, '')}\n\n${POINTER}` : POINTER, 'utf-8');
-    return path;
+    return { path, state: before === null ? 'new' : 'updated' };
 }
-function install(base, global) {
+function install(base, ids, global) {
     const skill = skillSource();
-    const touched = [];
-    for (const dir of global ? GLOBAL_SKILL_DIRS : SKILL_DIRS) {
-        const path = writeIfChanged((0, node_path_1.join)(base, ...dir, 'xflow', 'SKILL.md'), skill);
-        if (path)
-            touched.push(path);
+    const changes = [];
+    const seen = new Set();
+    const put = (path, content) => {
+        if (seen.has(path))
+            return;
+        seen.add(path);
+        const state = writeIfChanged(path, content);
+        if (state)
+            changes.push({ path, state });
+    };
+    for (const agent of AGENTS) {
+        if (!ids.includes(agent.id))
+            continue;
+        put(skillPath(base, agent, global), skill);
+        if (!global && agent.rule === true)
+            put((0, node_path_1.join)(base, ...CURSOR_RULE), cursorRule(skill));
     }
     // Project-level only: these have no global equivalents.
     if (!global) {
-        const rule = writeIfChanged((0, node_path_1.join)(base, ...CURSOR_RULE), cursorRule(skill));
-        if (rule)
-            touched.push(rule);
         const pointer = appendPointer(base);
         if (pointer)
-            touched.push(pointer);
+            changes.push(pointer);
     }
-    return touched;
+    return changes;
+}
+/** Defaults plus whatever is already installed, so an update run refreshes everything. */
+function defaultIds(base, global) {
+    const ids = new Set(global ? DEFAULT_GLOBAL : DEFAULT_PROJECT);
+    for (const agent of AGENTS) {
+        if (installed(base, agent, global))
+            ids.add(agent.id);
+    }
+    return [...ids];
 }
 /** Best-effort install from init and link: a failure must not break the linking. */
 function installSkillQuietly(base) {
     try {
-        if (install(base, false).length > 0) {
+        if (install(base, defaultIds(base, false), false).length > 0) {
             (0, ui_1.note)((0, ui_1.dim)('  The platform instructions are laid out for the AI agent'));
         }
     }
@@ -92,12 +119,86 @@ function installSkillQuietly(base) {
         (0, ui_1.note)((0, ui_1.dim)('  Could not lay out the AI agent instructions: xflow skills'));
     }
 }
-function skills(args) {
-    const global = (0, args_1.flagBool)(args, 'global');
-    const touched = install(global ? (0, node_os_1.homedir)() : process.cwd(), global);
-    for (const path of touched)
-        (0, ui_1.out)(path);
-    if (touched.length === 0)
+function pathLabel(agent, global) {
+    const dir = global ? agent.global : agent.project;
+    return (global ? ['~', ...dir] : dir).join('/');
+}
+function listAgents(base) {
+    (0, ui_1.table)(AGENTS.map((agent) => [
+        agent.id,
+        agent.label,
+        pathLabel(agent, false) + (installed(base, agent, false) ? ' *' : ''),
+        pathLabel(agent, true) + (installed(base, agent, true) ? ' *' : ''),
+    ]));
+    (0, ui_1.note)((0, ui_1.dim)('  * installed. Columns: id, agent, in the project, in the home folder'));
+    (0, ui_1.note)((0, ui_1.dim)('  Install without questions: xflow skills --agent <id,id> [--global]'));
+}
+async function pick(globalFlag) {
+    let global = globalFlag;
+    if (!globalFlag) {
+        const scope = await (0, prompt_1.select)('Where to install the xflow skill', [
+            { label: 'This project', hint: process.cwd() },
+            { label: 'Globally', hint: 'home folder, visible to every project' },
+        ]);
+        if (scope === null)
+            return null;
+        global = scope === 1;
+    }
+    const base = process.cwd();
+    const present = AGENTS.map((agent) => installed(base, agent, global));
+    const anyPresent = present.includes(true);
+    const defaults = global ? DEFAULT_GLOBAL : DEFAULT_PROJECT;
+    const picked = await (0, prompt_1.multiSelect)('Which agents get the skill', AGENTS.map((agent, i) => ({
+        label: agent.label,
+        hint: pathLabel(agent, global) + (present[i] ? ', installed' : ''),
+        checked: anyPresent ? present[i] : defaults.includes(agent.id),
+    })));
+    if (picked === null || picked.length === 0)
+        return null;
+    return { ids: picked.map((i) => AGENTS[i].id), global };
+}
+async function skills(args) {
+    const sub = args.words[0];
+    if (sub === 'list') {
+        listAgents(process.cwd());
+        return;
+    }
+    if (sub !== undefined) {
+        throw new errors_1.CliError(`Unknown command: skills ${sub}`, 'Available: xflow skills [list]');
+    }
+    let global = (0, args_1.flagBool)(args, 'global');
+    const agentFlag = (0, args_1.flagString)(args, 'agent');
+    if (args.flags.agent !== undefined && agentFlag === undefined) {
+        throw new errors_1.CliError('The --agent flag needs a value', 'For example: --agent claude,cursor. The ids: xflow skills list');
+    }
+    let ids;
+    if (agentFlag !== undefined) {
+        ids = agentFlag
+            .split(',')
+            .map((id) => id.trim())
+            .filter((id) => id.length > 0);
+        const known = new Set(AGENTS.map((agent) => agent.id));
+        const unknown = ids.filter((id) => !known.has(id));
+        if (unknown.length > 0 || ids.length === 0) {
+            throw new errors_1.CliError(unknown.length > 0 ? `Unknown agent: ${unknown.join(', ')}` : 'No agents named', 'The ids: xflow skills list');
+        }
+    }
+    else if (process.stdin.isTTY === true && process.stderr.isTTY === true && !(0, args_1.flagBool)(args, 'yes')) {
+        const picked = await pick(global);
+        if (picked === null) {
+            (0, ui_1.note)((0, ui_1.dim)('  nothing chosen, nothing changed'));
+            return;
+        }
+        ids = picked.ids;
+        global = picked.global;
+    }
+    else {
+        ids = defaultIds(process.cwd(), global);
+    }
+    const changes = install(process.cwd(), ids, global);
+    for (const change of changes)
+        (0, ui_1.out)(`${change.state === 'new' ? '+' : '~'} ${change.path}`);
+    if (changes.length === 0)
         (0, ui_1.note)((0, ui_1.dim)('  everything is already up to date'));
     (0, ui_1.ok)(global ? 'The xflow skill is available in every project' : 'The xflow skill is in place');
     (0, ui_1.note)((0, ui_1.dim)('  After a CLI update run the command again: the skill ships with it'));

package/dist/help.js

@@ -16,7 +16,7 @@ ${(0, ui_1.bold)('Getting started')}
   xflow init [dir]                new project from the platform template
   xflow templates                 which templates are available
   xflow link <id>                 link this folder to a project (id: xflow projects list)
-  xflow skills [--global]         refresh the platform instructions for an AI agent
+  xflow skills                    pick the agents that get the platform instructions
   xflow mcp install               give the agent platform access without a terminal
 
 ${(0, ui_1.bold)('Code')}
@@ -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
@@ -183,19 +198,23 @@ project from the ${(0, ui_1.bold)('project_id')} argument, not from your folder,
 An agent has no way to know about XFlow: the platform is not in its training. The
 instructions explain how to release and publish, where the design system components
 come from, and where to look for production errors. ${(0, ui_1.bold)('init')} and ${(0, ui_1.bold)('link')} lay them
-down on their own, so this command is for refreshing them after a CLI update: the two
-ship as one version.
+down on their own for the common agents, so this command exists to pick tools
+precisely and to refresh after a CLI update: the skill and the CLI ship as one version.
 
-The format is shared (agentskills.io) but the folders differ per tool, so we write all:
+Run in a terminal, it asks two questions: where (this project, or the home folder,
+which makes the skill visible in every project) and for which agents. Copies that are
+already installed come pre-selected and are updated in place. Without a terminal, in
+CI or when an agent runs the command, there are no questions: the defaults plus every
+already installed copy are refreshed.
 
-  .claude/skills/xflow/SKILL.md    Claude Code
-  .agents/skills/xflow/SKILL.md    Codex, OpenClaw
-  .cursor/rules/xflow.mdc          Cursor: it does not read the shared format
+  xflow skills list               the agents, their folders and what is installed
+  --agent claude,cursor           exact agents, no questions asked
+  --global                        the home folder instead of the project
+  --yes                           no questions: defaults plus what is installed
 
-  --global    the same in the home folder, which makes the skill visible in every
-              project. There ~/.codex/skills is added as well, because Codex looks in
-              its shared catalog only inside a repository. The Cursor rule and
-              AGENTS.md stay per project, they have no global counterpart
+The format is shared (agentskills.io) and inside a project most tools read the shared
+.agents/skills folder, so the paths differ mostly in the home directory. Cursor also
+gets .cursor/rules/xflow.mdc: its older versions do not read the shared format.
 
 Plus a few pointer lines in ${(0, ui_1.bold)('AGENTS.md')}. A skill is picked up lazily, only when its
 description matches the task, and "add a customers table" will not trigger it. AGENTS.md
@@ -229,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
@@ -243,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/prompt.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.multiSelect = multiSelect;
+exports.select = select;
+const node_readline_1 = require("node:readline");
+const errors_1 = require("./errors");
+const ui_1 = require("./ui");
+function render(lines, first) {
+    const up = first ? '' : `[${lines.length}A`;
+    process.stderr.write(up + lines.map((line) => `${line}\n`).join(''));
+}
+function listen(onKey) {
+    if (process.stdin.isTTY !== true) {
+        throw new errors_1.CliError('An interactive prompt needs a terminal', 'Pass the choice through flags instead');
+    }
+    (0, node_readline_1.emitKeypressEvents)(process.stdin);
+    const wasRaw = process.stdin.isRaw === true;
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    const handler = (_, key) => {
+        if (key)
+            onKey(key);
+    };
+    process.stdin.on('keypress', handler);
+    return () => {
+        process.stdin.off('keypress', handler);
+        process.stdin.setRawMode(wasRaw);
+        process.stdin.pause();
+    };
+}
+const isConfirm = (key) => key.name === 'return' || key.name === 'enter';
+const isCancel = (key) => key.name === 'escape' || (key.ctrl === true && key.name === 'c');
+/** Checkbox list. Resolves with the picked indexes, or null when cancelled. */
+function multiSelect(title, choices) {
+    return new Promise((resolve) => {
+        let cursor = 0;
+        let first = true;
+        const checked = choices.map((choice) => choice.checked === true);
+        const draw = () => {
+            render([
+                (0, ui_1.bold)(title),
+                ...choices.map((choice, i) => {
+                    const hint = choice.hint ? `  ${(0, ui_1.dim)(choice.hint)}` : '';
+                    return `${i === cursor ? '>' : ' '} ${checked[i] ? '[x]' : '[ ]'} ${choice.label}${hint}`;
+                }),
+                (0, ui_1.dim)('  up/down move, space toggle, enter confirm, esc cancel'),
+            ], first);
+            first = false;
+        };
+        const stop = listen((key) => {
+            if (key.name === 'up')
+                cursor = (cursor + choices.length - 1) % choices.length;
+            else if (key.name === 'down')
+                cursor = (cursor + 1) % choices.length;
+            else if (key.name === 'space')
+                checked[cursor] = !checked[cursor];
+            else if (isConfirm(key)) {
+                stop();
+                resolve(checked.flatMap((on, i) => (on ? [i] : [])));
+                return;
+            }
+            else if (isCancel(key)) {
+                stop();
+                resolve(null);
+                return;
+            }
+            else
+                return;
+            draw();
+        });
+        draw();
+    });
+}
+/** Radio list. Resolves with the picked index, or null when cancelled. */
+function select(title, choices) {
+    return new Promise((resolve) => {
+        let cursor = 0;
+        let first = true;
+        const draw = () => {
+            render([
+                (0, ui_1.bold)(title),
+                ...choices.map((choice, i) => {
+                    const hint = choice.hint ? `  ${(0, ui_1.dim)(choice.hint)}` : '';
+                    return `${i === cursor ? '>' : ' '} ${choice.label}${hint}`;
+                }),
+                (0, ui_1.dim)('  up/down move, enter confirm, esc cancel'),
+            ], first);
+            first = false;
+        };
+        const stop = listen((key) => {
+            if (key.name === 'up')
+                cursor = (cursor + choices.length - 1) % choices.length;
+            else if (key.name === 'down')
+                cursor = (cursor + 1) % choices.length;
+            else if (isConfirm(key)) {
+                stop();
+                resolve(cursor);
+                return;
+            }
+            else if (isCancel(key)) {
+                stop();
+                resolve(null);
+                return;
+            }
+            else
+                return;
+            draw();
+        });
+        draw();
+    });
+}

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.3.3';
+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.3.3",
+  "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

@@ -17,6 +17,26 @@ memory. If a command is not in the help output, it does not exist: guessing flag
 pointless. The CLI prints a hint with almost every error, read it in full, it usually
 contains the fix.
 
+## Hard rules
+
+These mistakes cost the most because nothing fails at the moment they are made, or
+the error points away from the cause. The sections below carry the details.
+
+1. Read environment variables literally: `process.env.API_KEY`. Destructuring
+   (`const { API_KEY } = process.env`) reads as no mention of the variable at all,
+   and it arrives empty.
+2. A value written with `xflow env set` reaches the functions on the next
+   `xflow deploy`, not at the moment it is written.
+3. Never delete a `functions/<name>/` directory unless the user asked for that
+   function to go. The next deploy removes it from the cloud together with its
+   schedules, and a function created again later gets a different address.
+4. An already applied migration is never re-run, so editing its file changes
+   nothing. A schema change is always a new file.
+5. When inserts start failing with `db_write_locked`, the database is over its plan
+   size. The fix is a migration that deletes data, never a rewrite of the failing SQL.
+6. In file storage, call `confirm` only after the PUT has finished, and send the same
+   `Content-Type` in both calls. Both mistakes answer 200 and break later.
+
 ## Plan limits
 
 The organization runs on a plan with finite limits: projects, cloud functions, developer
@@ -48,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.
@@ -142,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
@@ -222,6 +251,17 @@ To run a function on a timer: `xflow schedules set report "0 3 ? * * *"` (daily
 Six fields, UTC, and exactly one of day-of-month / day-of-week must be `?` — that is
 how Yandex wants it. A scheduled run reaches the handler as a POST with no headers.
 
+The pieces line up in one pass. From a new function to a verified schedule:
+
+```
+xflow env set SMTP_PASSWORD=...            # secrets first: values ride the next deploy
+# write functions/report/index.ts, reading process.env.SMTP_PASSWORD literally
+xflow deploy                               # ships the function, then builds the app
+xflow schedules set report "0 3 ? * * *"   # after the deploy: a schedule needs a deployed function
+xflow functions invoke report              # run it once, the way the app would
+xflow functions logs report                # empty output means it never crashed
+```
+
 ## Database
 
 Schema changes are files: `migrations/0001_init.sql`, `migrations/0002_orders.sql`, applied
@@ -245,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
@@ -325,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