@getxflow/cli 0.1.0 → 0.1.4

package/README.md

@@ -20,7 +20,11 @@ xflow publish
 | `init` / `link` | новый проект, связать папку с существующим |
 | `status` / `push` / `pull` | состояние, отправка и получение исходников |
 | `deploy` / `publish` / `rollback` / `deployments` | сборка, публикация, откат, история версий |
+| `db status` / `db migrate` | миграции из `migrations/*.sql` с гейтом на разрушающие |
 | `functions list` / `functions deploy` | облачные функции проекта из `functions/<имя>/index.ts` |
+| `functions invoke` / `functions logs` | вызвать функцию, посмотреть её падения со стеком |
+| `schedules list` / `set` / `rm` | запуск функций по времени (таймер-триггеры) |
+| `logs` | ошибки выложенного приложения в браузере |
 | `projects list` / `projects get` / `open` | проекты организации и адреса приложения |
 | `skills` | инструкция о платформе для ИИ-агента (формат [Agent Skills](https://agentskills.io)) |
 

package/dist/args.js

@@ -24,6 +24,8 @@ const BOOLEAN_FLAGS = new Set([
     'no-push',
     'skip-build',
     'all',
+    'dry-run',
+    'allow-destructive',
 ]);
 function parseArgs(argv) {
     const words = [];

package/dist/bin.js

@@ -11,7 +11,10 @@ const zip_1 = require("./zip");
 const version_1 = require("./version");
 const auth_1 = require("./commands/auth");
 const projects_1 = require("./commands/projects");
+const db_1 = require("./commands/db");
 const functions_1 = require("./commands/functions");
+const logs_1 = require("./commands/logs");
+const schedules_1 = require("./commands/schedules");
 const skills_1 = require("./commands/skills");
 const sources_1 = require("./commands/sources");
 const deploy_1 = require("./commands/deploy");
@@ -65,11 +68,46 @@ async function run(args) {
                 await (0, functions_1.functionsDeploy)(rest);
                 return;
             }
+            if (second === 'invoke') {
+                await (0, functions_1.functionsInvoke)(rest);
+                return;
+            }
+            if (second === 'logs') {
+                await (0, logs_1.functionsLogs)(rest);
+                return;
+            }
             if (second === undefined || second === 'list') {
                 await (0, functions_1.functionsList)();
                 return;
             }
-            throw new errors_1.CliError(`Неизвестная команда: functions ${second}`, 'Есть list и deploy');
+            throw new errors_1.CliError(`Неизвестная команда: functions ${second}`, 'Есть list, deploy, invoke и logs');
+        case 'logs':
+            await (0, logs_1.logs)(rest);
+            return;
+        case 'schedules':
+            if (second === 'set') {
+                await (0, schedules_1.schedulesSet)(rest);
+                return;
+            }
+            if (second === 'rm' || second === 'remove') {
+                await (0, schedules_1.schedulesRemove)(rest);
+                return;
+            }
+            if (second === undefined || second === 'list') {
+                await (0, schedules_1.schedulesList)();
+                return;
+            }
+            throw new errors_1.CliError(`Неизвестная команда: schedules ${second}`, 'Есть list, set и rm');
+        case 'db':
+            if (second === 'migrate') {
+                await (0, db_1.dbMigrate)(rest);
+                return;
+            }
+            if (second === undefined || second === 'status') {
+                await (0, db_1.dbStatus)();
+                return;
+            }
+            throw new errors_1.CliError(`Неизвестная команда: db ${second}`, 'Есть status и migrate');
         case 'status':
             await (0, sources_1.status)();
             return;

package/dist/commands/db.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dbStatus = dbStatus;
+exports.dbMigrate = dbMigrate;
+const node_fs_1 = require("node:fs");
+const node_crypto_1 = require("node:crypto");
+const node_path_1 = require("node:path");
+const api_1 = require("../api");
+const args_1 = require("../args");
+const config_1 = require("../config");
+const errors_1 = require("../errors");
+const session_1 = require("../session");
+const ui_1 = require("../ui");
+/**
+ * Миграции базы проекта.
+ *
+ * Файлы лежат в репозитории (`migrations/0001_init.sql`), историю применённых
+ * помнит сама база. Отсюда правило: локально мы только читаем и сортируем, а что
+ * из этого новое, решает сервер.
+ */
+const MIGRATIONS_DIR = 'migrations';
+function checksum(sql) {
+    return (0, node_crypto_1.createHash)('sha256').update(sql).digest('hex').slice(0, 16);
+}
+/** Порядок по имени файла: `0001_` идёт раньше `0002_`, это и есть очередь. */
+function readMigrations(root) {
+    const dir = (0, node_path_1.join)(root, MIGRATIONS_DIR);
+    if (!(0, node_fs_1.existsSync)(dir))
+        return [];
+    return (0, node_fs_1.readdirSync)(dir)
+        .filter((name) => name.toLowerCase().endsWith('.sql'))
+        .sort()
+        .map((file) => ({
+        name: file.replace(/\.sql$/i, ''),
+        sql: (0, node_fs_1.readFileSync)((0, node_path_1.join)(dir, file), 'utf-8'),
+    }));
+}
+function requireMigrations(root) {
+    const migrations = readMigrations(root);
+    if (migrations.length === 0) {
+        throw new errors_1.CliError(`В проекте нет миграций`, `Положите SQL в ${MIGRATIONS_DIR}/0001_init.sql и повторите`);
+    }
+    return migrations;
+}
+async function dbStatus() {
+    const { root, config } = (0, config_1.requireProject)();
+    const client = (0, session_1.connect)(config);
+    const local = readMigrations(root);
+    const history = await (0, api_1.apiJson)(client, `/api/v1/projects/${config.projectId}/db/migrate`);
+    const applied = new Map(history.applied.map((row) => [row.name, row]));
+    (0, ui_1.out)(`Схема: ${(0, ui_1.bold)(history.schema)}`);
+    (0, ui_1.out)('');
+    if (local.length === 0 && applied.size === 0) {
+        (0, ui_1.note)(`Миграций нет. Первая: ${MIGRATIONS_DIR}/0001_init.sql`);
+        return;
+    }
+    const rows = [];
+    for (const migration of local) {
+        const row = applied.get(migration.name);
+        if (!row) {
+            rows.push([migration.name, 'ждёт применения', '']);
+            continue;
+        }
+        const changed = row.checksum !== checksum(migration.sql);
+        rows.push([
+            migration.name,
+            changed ? 'применена, файл изменён' : 'применена',
+            (0, ui_1.formatAge)(row.applied_at),
+        ]);
+    }
+    // Применённое, чего нет локально: чаще всего чужая миграция из другого проекта
+    // на той же логической базе.
+    const localNames = new Set(local.map((migration) => migration.name));
+    for (const row of history.applied) {
+        if (!localNames.has(row.name))
+            rows.push([row.name, 'применена, файла нет', (0, ui_1.formatAge)(row.applied_at)]);
+    }
+    (0, ui_1.table)(rows);
+    if (rows.some((row) => row[1] === 'применена, файл изменён')) {
+        (0, ui_1.out)('');
+        (0, ui_1.warn)('Изменённый файл повторно не применится: заведите новую миграцию');
+    }
+}
+async function dbMigrate(args) {
+    const { root, config } = (0, config_1.requireProject)();
+    const client = (0, session_1.connect)(config);
+    const migrations = requireMigrations(root);
+    const dryRun = (0, args_1.flagBool)(args, 'dry-run');
+    (0, ui_1.step)(dryRun ? `Проверяю миграции (${migrations.length} в каталоге)` : `Применяю миграции (${migrations.length} в каталоге)`);
+    const result = await (0, api_1.apiJson)(client, `/api/v1/projects/${config.projectId}/db/migrate`, {
+        method: 'POST',
+        body: {
+            migrations,
+            dry_run: dryRun,
+            allow_destructive: (0, args_1.flagBool)(args, 'allow-destructive'),
+        },
+        timeoutMs: 300_000,
+    });
+    if (result.destructive.length > 0) {
+        (0, ui_1.warn)('Разрушающие операции:');
+        for (const hit of result.destructive)
+            (0, ui_1.note)((0, ui_1.dim)(`  ${hit}`));
+    }
+    if (result.dry_run) {
+        if (result.pending.length === 0) {
+            (0, ui_1.ok)('Применять нечего: все миграции уже в базе');
+            return;
+        }
+        (0, ui_1.out)('');
+        (0, ui_1.out)(`Будут применены (${result.pending.length}):`);
+        for (const name of result.pending)
+            (0, ui_1.out)(`  ${name}`);
+        (0, ui_1.note)((0, ui_1.dim)('  Пробный прогон: база не менялась'));
+        return;
+    }
+    for (const dump of result.dumps) {
+        (0, ui_1.note)((0, ui_1.dim)(`  Дамп ${dump.table}: строк ${dump.rows}${dump.truncated ? ' (обрезан по потолку)' : ''}, хранится ${result.dump_retention_days} суток`));
+    }
+    if (result.applied.length > 0) {
+        (0, ui_1.ok)(`Применено: ${result.applied.join(', ')}`);
+    }
+    else if (!result.failed) {
+        (0, ui_1.ok)('Применять нечего: все миграции уже в базе');
+    }
+    if (result.failed) {
+        throw new errors_1.CliError(`${result.failed.name}: ${result.failed.error}`, result.applied.length > 0
+            ? `Применённое до неё осталось в базе (${result.applied.join(', ')}), остальное не запускалось`
+            : 'База не изменилась: миграция откатилась целиком');
+    }
+}

package/dist/commands/deploy.js

@@ -14,6 +14,7 @@ const session_1 = require("../session");
 const tree_1 = require("../tree");
 const zip_1 = require("../zip");
 const ui_1 = require("../ui");
+const functions_1 = require("./functions");
 const sources_1 = require("./sources");
 /** Потолок артефакта на сервере. */
 const MAX_ARTIFACT_BYTES = 100 * 1024 * 1024;
@@ -55,6 +56,8 @@ async function deploy(args) {
         revision = (await (0, sources_1.pushSources)(root, config, client, { force: (0, args_1.flagBool)(args, 'force') })).revision;
     }
     if (!(0, args_1.flagBool)(args, 'skip-build')) {
+        // Перед сборкой, а не после: адреса функций попадают в бандл на этом шаге.
+        await (0, functions_1.refreshFunctionsEnv)(root, client, config.projectId);
         (0, ui_1.step)(`Сборка: ${buildCommand}`);
         await runBuild(buildCommand, root);
     }

package/dist/commands/functions.js

@@ -1,13 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.functionsList = functionsList;
+exports.refreshFunctionsEnv = refreshFunctionsEnv;
+exports.functionsInvoke = functionsInvoke;
 exports.functionsDeploy = functionsDeploy;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const api_1 = require("../api");
+const args_1 = require("../args");
 const config_1 = require("../config");
 const errors_1 = require("../errors");
 const session_1 = require("../session");
+const template_1 = require("../template");
 const ui_1 = require("../ui");
 const ENTRY_NAMES = ['index.ts', 'index.js', 'index.mjs'];
 /** Папка с функциями внутри проекта. Та же, что была до пивота: менять её незачем. */
@@ -77,6 +81,84 @@ async function functionsList() {
         fn.error_message ?? fn.invoke_url ?? '',
     ]));
 }
+/**
+ * Записать адреса функций в `.env`, откуда их заберёт сборщик.
+ *
+ * Подставляем на сборке, а не спрашиваем у платформы в рантайме: иначе каждый
+ * запуск приложения начинался бы с похода к нам, и мы стали бы обязательным
+ * участником работы чужого приложения.
+ */
+async function refreshFunctionsEnv(root, client, projectId) {
+    const card = await (0, api_1.apiJson)(client, `/api/v1/projects/${projectId}`);
+    // Файла может не быть вовсе: в исходники он не уходит, а клон делают из git.
+    // Дописывать в такой один адрес функции бессмысленно — без токена вызов всё
+    // равно получит 401, поэтому восстанавливаем целиком, как это делает link.
+    if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(root, '.env')) && card.project_token) {
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(root, '.env'), (0, template_1.envFile)(card.project_token, client.apiUrl, card.functions), 'utf-8');
+    }
+    else {
+        (0, template_1.writeEnvValue)(root, template_1.FUNCTIONS_ENV_KEY, (0, template_1.functionsEnvValue)(card.functions));
+    }
+    return card.functions.filter((fn) => fn.invoke_url).map((fn) => fn.name);
+}
+/** Ответ функции: JSON разворачиваем, прочее отдаём как есть. */
+function prettyBody(text) {
+    try {
+        return JSON.stringify(JSON.parse(text), null, 2);
+    }
+    catch {
+        return text;
+    }
+}
+/**
+ * Вызвать функцию так же, как её вызывает приложение.
+ *
+ * Токен проекта берём из карточки на платформе, а не из локального `.env`: в
+ * свежем клоне файла нет вовсе, а команда должна работать сразу после link.
+ */
+async function functionsInvoke(args) {
+    const { config } = (0, config_1.requireProject)();
+    const client = (0, session_1.connect)(config);
+    const name = args.words[1];
+    if (!name)
+        throw new errors_1.CliError('Нужно имя функции', 'Что выложено: xflow functions list');
+    const card = await (0, api_1.apiJson)(client, `/api/v1/projects/${config.projectId}`);
+    const fn = card.functions.find((item) => item.name === name);
+    if (!fn || !fn.invoke_url) {
+        throw new errors_1.CliError(`Функция ${name} не выложена`, card.functions.length > 0
+            ? `Выложены: ${card.functions.map((item) => item.name).join(', ')}`
+            : `Выкатить: xflow functions deploy ${name}`);
+    }
+    const data = (0, args_1.flagString)(args, 'data');
+    const method = ((0, args_1.flagString)(args, 'method') ?? (data ? 'POST' : 'GET')).toUpperCase();
+    const sendsBody = method !== 'GET' && method !== 'HEAD';
+    const started = Date.now();
+    let response;
+    try {
+        response = await fetch(fn.invoke_url, {
+            method,
+            headers: {
+                'Content-Type': 'application/json',
+                'X-Project-Token': card.project_token ?? '',
+            },
+            body: sendsBody ? (data ?? '{}') : undefined,
+            // У функции свой потолок в 30 секунд: ждём чуть дольше, чтобы увидеть её
+            // собственный таймаут, а не свой.
+            signal: AbortSignal.timeout(40_000),
+        });
+    }
+    catch (e) {
+        throw new errors_1.CliError(`Функция не ответила: ${e instanceof Error ? e.message : String(e)}`, 'Проверьте, что она выложена: xflow functions list');
+    }
+    const elapsed = Date.now() - started;
+    const text = await response.text();
+    (0, ui_1.note)((0, ui_1.dim)(`${response.status} ${response.statusText} за ${elapsed} мс`));
+    if (text)
+        (0, ui_1.out)(prettyBody(text));
+    if (!response.ok) {
+        throw new errors_1.CliError(`Функция ответила ${response.status}`, `Стек и вывод консоли: xflow functions logs ${name}`);
+    }
+}
 async function functionsDeploy(args) {
     const { root, config } = (0, config_1.requireProject)();
     const client = (0, session_1.connect)(config);
@@ -100,4 +182,6 @@ async function functionsDeploy(args) {
             (0, ui_1.note)((0, ui_1.dim)(`  Секреты организации в окружении: ${result.secrets.join(', ')}`));
         }
     }
+    const available = await refreshFunctionsEnv(root, client, config.projectId);
+    (0, ui_1.note)((0, ui_1.dim)(`  Адреса в .env обновлены (${available.join(', ')}). Во фронтенде: xflow.functions.invoke('${names[0]}')`));
 }

package/dist/commands/logs.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logs = logs;
+exports.functionsLogs = functionsLogs;
+const api_1 = require("../api");
+const args_1 = require("../args");
+const config_1 = require("../config");
+const session_1 = require("../session");
+const ui_1 = require("../ui");
+const DEFAULT_LIMIT = 10;
+/** Стек с хвостом консоли бывает длинным: показываем начало, оно и есть причина. */
+const STACK_MAX_LINES = 14;
+function stamp(iso) {
+    const date = new Date(iso);
+    const pad = (value) => String(value).padStart(2, '0');
+    return `${pad(date.getDate())}.${pad(date.getMonth() + 1)} ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+}
+async function fetchLogs(source, name, args) {
+    const { config } = (0, config_1.requireProject)();
+    const client = (0, session_1.connect)(config);
+    const query = new URLSearchParams({ source, limit: String((0, args_1.flagNumber)(args, 'limit') ?? DEFAULT_LIMIT) });
+    if (name)
+        query.set('name', name);
+    const data = await (0, api_1.apiJson)(client, `/api/v1/projects/${config.projectId}/logs?${query.toString()}`);
+    return data.logs;
+}
+/** Свежее — внизу: так последняя ошибка оказывается перед глазами, а не уезжает вверх. */
+function render(rows) {
+    for (const row of [...rows].reverse()) {
+        const label = row.source === 'function' ? (row.function ?? 'функция') : 'браузер';
+        (0, ui_1.out)(`${(0, ui_1.dim)(stamp(row.timestamp))}  ${(0, ui_1.bold)(label)}  ${row.message}`);
+        if (row.stack) {
+            const lines = row.stack.split('\n');
+            for (const line of lines.slice(0, STACK_MAX_LINES))
+                (0, ui_1.out)((0, ui_1.dim)(`    ${line}`));
+            if (lines.length > STACK_MAX_LINES)
+                (0, ui_1.out)((0, ui_1.dim)(`    … ещё строк: ${lines.length - STACK_MAX_LINES}`));
+        }
+        (0, ui_1.out)('');
+    }
+}
+async function logs(args) {
+    const rows = await fetchLogs('client', undefined, args);
+    if (rows.length === 0) {
+        (0, ui_1.note)('Ошибок из браузера нет');
+        (0, ui_1.note)((0, ui_1.dim)('  Сюда попадают падения выложенного приложения, а не локального npm run dev'));
+        return;
+    }
+    render(rows);
+}
+async function functionsLogs(args) {
+    const name = args.words[1];
+    const rows = await fetchLogs('function', name, args);
+    if (rows.length === 0) {
+        (0, ui_1.note)(name ? `Функция ${name} не падала` : 'Функции не падали');
+        (0, ui_1.note)((0, ui_1.dim)('  Сюда попадают только неудачные вызовы: успешные ничего не пишут'));
+        return;
+    }
+    render(rows);
+}

package/dist/commands/projects.js

@@ -128,8 +128,8 @@ async function link(args) {
     // В исходники .env не уходит, поэтому в свежем клоне его нет вовсе, и приложение
     // молча теряет доступ к облачным функциям. Восстанавливаем, но чужой не трогаем.
     if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(dir, '.env')) && card.project_token) {
-        write(dir, '.env', (0, template_1.envFile)(card.project_token, client.apiUrl));
-        (0, ui_1.note)((0, ui_1.dim)('  Создан .env с токеном проекта'));
+        write(dir, '.env', (0, template_1.envFile)(card.project_token, client.apiUrl, card.functions));
+        (0, ui_1.note)((0, ui_1.dim)('  Создан .env с токеном проекта и адресами функций'));
     }
     (0, ui_1.ok)(`Папка связана с проектом «${card.name}»`);
     (0, ui_1.note)((0, ui_1.dim)(`  ${(0, node_path_1.join)(dir, config_1.CONFIG_FILE)}`));

package/dist/commands/schedules.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.schedulesList = schedulesList;
+exports.schedulesSet = schedulesSet;
+exports.schedulesRemove = schedulesRemove;
+const api_1 = require("../api");
+const args_1 = require("../args");
+const config_1 = require("../config");
+const errors_1 = require("../errors");
+const session_1 = require("../session");
+const ui_1 = require("../ui");
+async function schedulesList() {
+    const { config } = (0, config_1.requireProject)();
+    const client = (0, session_1.connect)(config);
+    const data = await (0, api_1.apiJson)(client, `/api/v1/projects/${config.projectId}/schedules`);
+    if (data.schedules.length === 0) {
+        (0, ui_1.note)('Расписаний нет');
+        (0, ui_1.note)((0, ui_1.dim)('  Запускать функцию по времени: xflow schedules set <функция> "0 3 ? * * *"'));
+        return;
+    }
+    (0, ui_1.table)(data.schedules.map((row) => [
+        row.function,
+        row.cron,
+        row.description === row.cron ? '' : row.description,
+        row.status === 'active' ? '' : (row.error ?? row.status),
+    ]));
+}
+async function schedulesSet(args) {
+    const { config } = (0, config_1.requireProject)();
+    const client = (0, session_1.connect)(config);
+    const functionName = args.words[1];
+    const cron = args.words[2];
+    if (!functionName || !cron) {
+        throw new errors_1.CliError('Нужны имя функции и расписание', 'Например: xflow schedules set nightly-report "0 3 ? * * *" — каждый день в 03:00 UTC');
+    }
+    const row = await (0, api_1.apiJson)(client, `/api/v1/projects/${config.projectId}/schedules`, {
+        method: 'POST',
+        body: { function: functionName, cron, payload: (0, args_1.flagString)(args, 'payload') ?? null },
+    });
+    (0, ui_1.ok)(`${(0, ui_1.bold)(row.function)} запускается ${row.description}`);
+    (0, ui_1.note)((0, ui_1.dim)(`  Время в UTC. Проверить вручную: xflow functions invoke ${row.function}`));
+}
+async function schedulesRemove(args) {
+    const { config } = (0, config_1.requireProject)();
+    const client = (0, session_1.connect)(config);
+    const functionName = args.words[1];
+    if (!functionName) {
+        throw new errors_1.CliError('Нужно имя функции', 'Что запускается по времени: xflow schedules list');
+    }
+    const cron = args.words[2];
+    const query = new URLSearchParams({ function: functionName });
+    if (cron)
+        query.set('cron', cron);
+    const result = await (0, api_1.apiJson)(client, `/api/v1/projects/${config.projectId}/schedules?${query.toString()}`, { method: 'DELETE' });
+    if (result.removed === 0) {
+        (0, ui_1.note)(`У функции ${functionName} нет такого расписания`);
+        return;
+    }
+    (0, ui_1.ok)(`Снято расписаний: ${result.removed}`);
+}

package/dist/help.js

@@ -12,121 +12,207 @@ function help(topic) {
         (0, ui_1.out)(TOPICS[topic]);
         return;
     }
-    (0, ui_1.out)(`${(0, ui_1.bold)('xflow')} ${(0, ui_1.dim)(version_1.CLI_VERSION)} — хостинг приложений XFlow
-
-${(0, ui_1.bold)('Начало работы')}
-  xflow login                     вход через браузер
-  xflow init [папка]              новый проект из шаблона платформы
-  xflow templates                 какие шаблоны доступны
-  xflow link <id>                 связать текущую папку с существующим проектом
-  xflow skills [--global]         положить инструкцию о платформе для ИИ-агента
-
-${(0, ui_1.bold)('Код')}
-  xflow status                    что на сервере и чем отличается локальная копия
-  xflow push [--force]            отправить исходники новой ревизией
-  xflow pull [--into dir] [--revision N]
-                                  забрать исходники (по умолчанию последнюю ревизию)
-
-${(0, ui_1.bold)('Выкладка')}
-  xflow deploy [--no-push] [--skip-build]
-                                  отправить код, собрать локально и выложить на dev
-  xflow publish                   показать dev-версию посетителям
-  xflow rollback <номер версии>    вернуть dev-адрес на прошлую версию
-  xflow deployments               история версий
-
-${(0, ui_1.bold)('Функции')}
-  xflow functions list            что выложено
-  xflow functions deploy [имя]    собрать и выкатить функцию
-
-${(0, ui_1.bold)('Справочное')}
-  xflow projects list             проекты организации
-  xflow projects get [id]         карточка проекта
-  xflow open [--live]             открыть приложение в браузере
-  xflow whoami                    чей ключ и что он может
-  xflow logout                    забыть ключ
-
-${(0, ui_1.bold)('Окружение')}
-  XFLOW_TOKEN                     ключ доступа (для CI: вместо xflow login)
-  XFLOW_API_URL                   адрес платформы, если он не app.getxflow.com
-
+    (0, ui_1.out)(`${(0, ui_1.bold)('xflow')} ${(0, ui_1.dim)(version_1.CLI_VERSION)} — хостинг приложений XFlow
+
+${(0, ui_1.bold)('Начало работы')}
+  xflow login                     вход через браузер
+  xflow init [папка]              новый проект из шаблона платформы
+  xflow templates                 какие шаблоны доступны
+  xflow link <id>                 связать текущую папку с существующим проектом
+  xflow skills [--global]         положить инструкцию о платформе для ИИ-агента
+
+${(0, ui_1.bold)('Код')}
+  xflow status                    что на сервере и чем отличается локальная копия
+  xflow push [--force]            отправить исходники новой ревизией
+  xflow pull [--into dir] [--revision N]
+                                  забрать исходники (по умолчанию последнюю ревизию)
+
+${(0, ui_1.bold)('Выкладка')}
+  xflow deploy [--no-push] [--skip-build]
+                                  отправить код, собрать локально и выложить на dev
+  xflow publish                   показать dev-версию посетителям
+  xflow rollback <номер версии>    вернуть dev-адрес на прошлую версию
+  xflow deployments               история версий
+
+${(0, ui_1.bold)('Функции')}
+  xflow functions list            что выложено
+  xflow functions deploy [имя]    собрать и выкатить функцию
+  xflow functions invoke <имя> [--data '{"a":1}']
+                                  вызвать функцию и показать ответ
+  xflow functions logs [имя]      падения функций: стек и вывод консоли
+  xflow schedules list            что запускается по времени
+  xflow schedules set <имя> "0 3 ? * * *"
+                                  запускать функцию по расписанию (UTC)
+  xflow schedules rm <имя>        снять расписание
+
+${(0, ui_1.bold)('База данных')}
+  xflow db status                 какие миграции применены, а какие ждут
+  xflow db migrate [--dry-run] [--allow-destructive]
+                                  применить миграции из migrations/*.sql
+
+${(0, ui_1.bold)('Справочное')}
+  xflow logs [--limit N]          ошибки выложенного приложения в браузере
+  xflow projects list             проекты организации
+  xflow projects get [id]         карточка проекта
+  xflow open [--live]             открыть приложение в браузере
+  xflow whoami                    чей ключ и что он может
+  xflow logout                    забыть ключ
+
+${(0, ui_1.bold)('Окружение')}
+  XFLOW_TOKEN                     ключ доступа (для CI: вместо xflow login)
+  XFLOW_API_URL                   адрес платформы, если он не app.getxflow.com
+
 Подробнее о команде: xflow help <команда>`);
 }
 const TOPICS = {
-    skills: `${(0, ui_1.bold)('xflow skills')} — инструкция о платформе для ИИ-агента
-
-Кладёт файл в формате Agent Skills (agentskills.io): что такое XFlow, как выкладывать
-и публиковать, откуда брать компоненты дизайн-системы, где смотреть ошибки прода.
-Агент подхватывает его сам, когда задача про платформу, и не тратит контекст в
-остальное время.
-
-Файл общий для инструментов, а папки у них разные, поэтому кладём в обе:
-${(0, ui_1.bold)('.claude/skills/xflow/')} читает Claude Code, ${(0, ui_1.bold)('.agents/skills/xflow/')} — Codex и OpenClaw.
-
-  --global    положить в домашнюю папку, тогда скилл виден во всех проектах
-
-${(0, ui_1.bold)('AGENTS.md')} и ${(0, ui_1.bold)('CLAUDE.md')} команда не трогает: это ваши файлы, в них ваши правила.
-Наше знание живёт в своей папке и переустанавливается поверх без спора за файл.
-
+    db: `${(0, ui_1.bold)('xflow db migrate')} — применить миграции
+
+Файлы лежат в репозитории: ${(0, ui_1.bold)('migrations/0001_init.sql')}, ${(0, ui_1.bold)('migrations/0002_orders.sql')} и так
+далее. Порядок — по имени файла, поэтому номер в начале обязателен. Каждая миграция
+применяется своей транзакцией, история хранится в самой базе, и повторно применённое
+не запускается.
+
+  --dry-run              показать, что применится, и не трогать базу
+  --allow-destructive    разрешить операции, уничтожающие данные
+
+Про разрушающие. Истории базы платформа не хранит и бэкапов не делает, поэтому
+${(0, ui_1.bold)('DROP TABLE')}, ${(0, ui_1.bold)('DROP COLUMN')}, ${(0, ui_1.bold)('TRUNCATE')} и ${(0, ui_1.bold)('DELETE FROM')} без условия
+отклоняются без явного флага. С флагом содержимое затронутых таблиц уезжает в дамп
+и хранится 7 суток — это страховка «сразу заметил», а не резервная копия.
+${(0, ui_1.bold)('DROP DATABASE')} не пропускается никогда: база общая для организации.
+
+Изменять уже применённый файл бесполезно: сверка идёт по имени, а не по
+содержимому. ${(0, ui_1.bold)('xflow db status')} такой файл покажет отдельно — заводите новую
+миграцию.
+
+Одна логическая база может быть привязана к нескольким проектам, поэтому в истории
+попадаются миграции, которых нет в вашем репозитории. Это нормально, но означает,
+что ваша миграция может сломать чужое приложение.`,
+    logs: `${(0, ui_1.bold)('xflow logs')} и ${(0, ui_1.bold)('xflow functions logs')} — ошибки проекта
+
+Один поток на проект: падения выложенного приложения в браузере и падения
+облачных функций. Хранятся последние 200 записей, дальше вытесняются.
+
+  --limit N          сколько показать (по умолчанию 10)
+
+Функция сообщает о падении сама: свои логи Yandex наружу отдаёт только по gRPC,
+поэтому обёртка ловит исключение, уносит вместе с ним хвост консоли (последние 40
+строк ${(0, ui_1.bold)('console.log')} этого вызова) и отправляет на платформу. Успешные вызовы не
+пишут ничего: иначе каждый запрос платил бы за это задержкой.
+
+Не попадёт сюда: падение на старте модуля (функция не успевает дойти до обёртки),
+превышение 30 секунд и нехватка памяти. Такое видно ответом на
+${(0, ui_1.bold)('xflow functions invoke')}.
+
+Ошибки браузера собирает ${(0, ui_1.bold)('src/utils/error-logger.ts')} шаблона и только с
+выложенных адресов: локальный ${(0, ui_1.bold)('npm run dev')} сюда не пишет.`,
+    schedules: `${(0, ui_1.bold)('xflow schedules')} — запуск функций по времени
+
+Расписание это таймер-триггер Yandex: он зовёт функцию сам, без участия
+приложения и браузера.
+
+  xflow schedules set отчёт "0 3 ? * * *"     каждый день в 03:00
+  xflow schedules set сводка "0 */4 ? * * *"  каждые 4 часа
+  xflow schedules rm отчёт                    снять все расписания функции
+
+Формат из шести полей: ${(0, ui_1.bold)('минуты часы день-месяца месяц день-недели год')}. Ровно одно
+из полей «День месяца» и «День недели» должно быть ${(0, ui_1.bold)('?')} — это не наша причуда, так
+устроен Яндекс. ${(0, ui_1.bold)('Время всегда UTC')}, местное он не знает.
+
+  --payload '{"режим":"полный"}'   тело, которое получит функция
+
+Запуск по расписанию приходит хендлеру как POST без заголовков, и токен проекта
+у него не проверяется: снаружи такое событие не подделать. Функция при этом должна
+быть уже выложена — расписание ссылается на неё, а не наоборот.
+
+Упавший запуск виден в ${(0, ui_1.bold)('xflow functions logs')}: по расписанию за функцией никто не
+смотрит, поэтому обёртка отчитывается о падении так же, как при обычном вызове.`,
+    invoke: `${(0, ui_1.bold)('xflow functions invoke')} <имя> — вызвать функцию
+
+Вызывает так же, как её вызывает приложение: с заголовком X-Project-Token.
+Токен берётся из карточки проекта на платформе, локальный .env не нужен.
+
+  --data '{"a":1}'   тело запроса (по умолчанию метод становится POST)
+  --method GET       другой метод
+
+Печатает статус, время ответа и тело. Ненулевой код возврата на статусе 4xx и
+5xx: в CI такой вызов должен ронять шаг. Причину падения показывает
+${(0, ui_1.bold)('xflow functions logs <имя>')}.`,
+    skills: `${(0, ui_1.bold)('xflow skills')} — инструкция о платформе для ИИ-агента
+
+Кладёт файл в формате Agent Skills (agentskills.io): что такое XFlow, как выкладывать
+и публиковать, откуда брать компоненты дизайн-системы, где смотреть ошибки прода.
+Агент подхватывает его сам, когда задача про платформу, и не тратит контекст в
+остальное время.
+
+Файл общий для инструментов, а папки у них разные, поэтому кладём в обе:
+${(0, ui_1.bold)('.claude/skills/xflow/')} читает Claude Code, ${(0, ui_1.bold)('.agents/skills/xflow/')} — Codex и OpenClaw.
+
+  --global    положить в домашнюю папку, тогда скилл виден во всех проектах
+
+${(0, ui_1.bold)('AGENTS.md')} и ${(0, ui_1.bold)('CLAUDE.md')} команда не трогает: это ваши файлы, в них ваши правила.
+Наше знание живёт в своей папке и переустанавливается поверх без спора за файл.
+
 Скилл едет вместе с CLI, поэтому после обновления пакета команду стоит повторить.`,
-    push: `${(0, ui_1.bold)('xflow push')} — отправить исходники
-
-Уходит вся рабочая копия целиком, одной ревизией. Не отправляются: node_modules,
-.git, dist, build, .next, любые .env, а также всё, что перечислено в .xflowignore
-и в поле ignore файла xflow.json.
-
-Если на сервере ревизия новее той, от которой вы работали, push отклоняется.
-Это значит, что кто-то запушил раньше: заберите его правки рядом
-(${(0, ui_1.bold)('xflow pull --into ./server-copy')}), сведите их у себя в git и повторите.
-
---force перетирает серверную ревизию. Перед этим CLI показывает, чью работу вы
-затираете, и просит подтверждение вводом имени проекта. В неинтерактивном режиме
-(CI, запуск агентом) подтвердить нельзя: расхождение версий должно ронять сборку,
+    push: `${(0, ui_1.bold)('xflow push')} — отправить исходники
+
+Уходит вся рабочая копия целиком, одной ревизией. Не отправляются: node_modules,
+.git, dist, build, .next, любые .env, а также всё, что перечислено в .xflowignore
+и в поле ignore файла xflow.json.
+
+Если на сервере ревизия новее той, от которой вы работали, push отклоняется.
+Это значит, что кто-то запушил раньше: заберите его правки рядом
+(${(0, ui_1.bold)('xflow pull --into ./server-copy')}), сведите их у себя в git и повторите.
+
+--force перетирает серверную ревизию. Перед этим CLI показывает, чью работу вы
+затираете, и просит подтверждение вводом имени проекта. В неинтерактивном режиме
+(CI, запуск агентом) подтвердить нельзя: расхождение версий должно ронять сборку,
 а не молча уничтожать чужую работу.`,
-    pull: `${(0, ui_1.bold)('xflow pull')} — забрать исходники
-
-По умолчанию забирает последнюю ревизию в папку проекта и отказывается писать в
-непустую: слить изменения платформа не умеет, это работа git.
-
-  --into <папка>     выгрузить рядом, чтобы сравнить
-  --revision <N>     конкретная ревизия (список: xflow deployments)
+    pull: `${(0, ui_1.bold)('xflow pull')} — забрать исходники
+
+По умолчанию забирает последнюю ревизию в папку проекта и отказывается писать в
+непустую: слить изменения платформа не умеет, это работа git.
+
+  --into <папка>     выгрузить рядом, чтобы сравнить
+  --revision <N>     конкретная ревизия (список: xflow deployments)
   --force            перезаписать папку целиком`,
-    deploy: `${(0, ui_1.bold)('xflow deploy')} — собрать и выложить
-
-Три шага: отправка исходников, локальная сборка, заливка результата. Команда
-сборки и каталог результата берутся из xflow.json (по умолчанию npm run build
-и dist).
-
-  --no-push       не отправлять исходники, выложить из последней серверной ревизии
-  --skip-build    не собирать, взять готовый каталог сборки
-  --force         разрешить перезапись серверной ревизии при отправке
-
-Сборка идёт на вашей машине, поэтому её результат зависит от вашей версии Node.
-Платформа раздаёт статику: сборка без index.html в корне отклоняется.
-
+    deploy: `${(0, ui_1.bold)('xflow deploy')} — собрать и выложить
+
+Три шага: отправка исходников, локальная сборка, заливка результата. Команда
+сборки и каталог результата берутся из xflow.json (по умолчанию npm run build
+и dist).
+
+  --no-push       не отправлять исходники, выложить из последней серверной ревизии
+  --skip-build    не собирать, взять готовый каталог сборки
+  --force         разрешить перезапись серверной ревизии при отправке
+
+Сборка идёт на вашей машине, поэтому её результат зависит от вашей версии Node.
+Платформа раздаёт статику: сборка без index.html в корне отклоняется.
+
 Выложенное видно только по dev-адресу. Посетителям — после ${(0, ui_1.bold)('xflow publish')}.`,
-    init: `${(0, ui_1.bold)('xflow init')} [папка] — новый проект
-
-Разворачивает шаблон платформы: React на Vite, Tailwind, набор компонентов
-(${(0, ui_1.bold)('src/components/ui')}) и готовые блоки (${(0, ui_1.bold)('src/components/blocks')}) — таблица,
-форма, фильтры, канбан, графики. Тот же шаблон получают проекты, созданные в вебе,
-поэтому приложения выглядят одинаково.
-
-Строить интерфейс поверх этих компонентов и токенов из ${(0, ui_1.bold)('src/index.css')} — не
-формальность: своя палитра поверх них выглядит чужеродно внутри платформы.
-
-  --name <имя>        имя проекта (по умолчанию — имя папки)
-  --template <id>     другой шаблон (список: xflow templates)
-  --database <id>     привязать логическую базу организации
-
-Порядок: проект заводится на платформе первым, потому что без него неоткуда взять
-токен для .env. Если запись файлов сорвётся, проект останется пустым, и CLI скажет,
+    init: `${(0, ui_1.bold)('xflow init')} [папка] — новый проект
+
+Разворачивает шаблон платформы: React на Vite, Tailwind, набор компонентов
+(${(0, ui_1.bold)('src/components/ui')}) и готовые блоки (${(0, ui_1.bold)('src/components/blocks')}) — таблица,
+форма, фильтры, канбан, графики. Тот же шаблон получают проекты, созданные в вебе,
+поэтому приложения выглядят одинаково.
+
+Строить интерфейс поверх этих компонентов и токенов из ${(0, ui_1.bold)('src/index.css')} — не
+формальность: своя палитра поверх них выглядит чужеродно внутри платформы.
+
+  --name <имя>        имя проекта (по умолчанию — имя папки)
+  --template <id>     другой шаблон (список: xflow templates)
+  --database <id>     привязать логическую базу организации
+
+Порядок: проект заводится на платформе первым, потому что без него неоткуда взять
+токен для .env. Если запись файлов сорвётся, проект останется пустым, и CLI скажет,
 как подобрать его командой link.`,
-    rollback: `${(0, ui_1.bold)('xflow rollback')} <номер версии> — вернуть прошлую сборку
-
-Переключает dev-адрес на выбранную версию. Возвращается только сборка: исходники
-остаются на своей ревизии, и вернуть их — отдельное решение
-(${(0, ui_1.bold)('xflow pull --revision N --into ./старая-версия')}).
-
-Посетители продолжают видеть опубликованную версию, пока не выполнен
+    rollback: `${(0, ui_1.bold)('xflow rollback')} <номер версии> — вернуть прошлую сборку
+
+Переключает dev-адрес на выбранную версию. Возвращается только сборка: исходники
+остаются на своей ревизии, и вернуть их — отдельное решение
+(${(0, ui_1.bold)('xflow pull --revision N --into ./старая-версия')}).
+
+Посетители продолжают видеть опубликованную версию, пока не выполнен
 ${(0, ui_1.bold)('xflow publish')}.`,
 };

package/dist/template.js

@@ -1,17 +1,12 @@
 "use strict";
-/**
- * Файлы, которые CLI добавляет поверх шаблона платформы.
- *
- * Сам шаблон приезжает архивом с платформы (`GET /api/v1/templates/{id}/archive`)
- * и здесь не дублируется: своя копия неизбежно разъехалась бы с той, из которой
- * создаются проекты в вебе, и приложения перестали бы выглядеть одинаково.
- *
- * Здесь только то, чего в шаблоне нет и быть не может: `.env` с токеном
- * конкретного проекта и правила для git.
- */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.FUNCTIONS_ENV_KEY = void 0;
+exports.functionsEnvValue = functionsEnvValue;
 exports.envFile = envFile;
+exports.writeEnvValue = writeEnvValue;
 exports.scaffoldFiles = scaffoldFiles;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
 const GITIGNORE = `node_modules/
 dist/
 .xflow/
@@ -36,12 +31,46 @@ xflow publish     # показать dev-версию посетителям
 
 Полезное: \`xflow status\` — что на сервере, \`xflow deployments\` — история версий.
 `;
+/** Адреса облачных функций для сборки: имя → URL, одной строкой JSON. */
+exports.FUNCTIONS_ENV_KEY = 'VITE_XFLOW_FUNCTIONS';
+function functionsEnvValue(functions) {
+    const map = {};
+    for (const fn of functions) {
+        if (fn.invoke_url)
+            map[fn.name] = fn.invoke_url;
+    }
+    return JSON.stringify(map);
+}
 /**
  * `.env` в исходники не уходит (его пропускают и push, и сервер), поэтому в свежем
  * клоне его восстанавливает `xflow link`.
  */
-function envFile(projectToken, apiUrl) {
-    return `VITE_XFLOW_PROJECT_TOKEN=${projectToken}\nVITE_XFLOW_API_URL=${apiUrl.replace(/^https?:\/\//, '')}\n`;
+function envFile(projectToken, apiUrl, functions = []) {
+    return [
+        `VITE_XFLOW_PROJECT_TOKEN=${projectToken}`,
+        `VITE_XFLOW_API_URL=${apiUrl.replace(/^https?:\/\//, '')}`,
+        `${exports.FUNCTIONS_ENV_KEY}=${functionsEnvValue(functions)}`,
+        '',
+    ].join('\n');
+}
+/**
+ * Обновить одну переменную в `.env`, не трогая остальные.
+ *
+ * Файл наш, но живёт у разработчика: рядом с нашими тремя строками у него может
+ * лежать что угодно своё, и переписывать файл целиком мы не вправе.
+ */
+function writeEnvValue(root, key, value) {
+    const path = (0, node_path_1.join)(root, '.env');
+    const line = `${key}=${value}`;
+    if (!(0, node_fs_1.existsSync)(path)) {
+        (0, node_fs_1.writeFileSync)(path, `${line}\n`, 'utf-8');
+        return;
+    }
+    const text = (0, node_fs_1.readFileSync)(path, 'utf-8');
+    const existing = new RegExp(`^${key}=.*$`, 'm');
+    const next = existing.test(text) ? text.replace(existing, line) : `${text.replace(/\n*$/, '\n')}${line}\n`;
+    if (next !== text)
+        (0, node_fs_1.writeFileSync)(path, next, 'utf-8');
 }
 function scaffoldFiles(projectName) {
     return [

package/dist/version.js

@@ -6,6 +6,6 @@ exports.DEFAULT_API_URL = exports.CLI_VERSION = void 0;
  * рантайме нельзя, после сборки он лежит на уровень выше dist и в бандл не
  * попадает.
  */
-exports.CLI_VERSION = '0.1.0';
+exports.CLI_VERSION = '0.1.4';
 /** Адрес платформы по умолчанию. Переопределяется XFLOW_API_URL и полем `api` в xflow.json. */
 exports.DEFAULT_API_URL = 'https://app.getxflow.com';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getxflow/cli",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "description": "CLI платформы XFlow: синхронизация кода, деплой и публикация приложений",
   "license": "UNLICENSED",
   "engines": {

package/skills/xflow/SKILL.md

@@ -43,13 +43,44 @@ with `xflow functions deploy` (one name to deploy a single function, no name for
 list what is live with `xflow functions list`. The handler returns
 `{ statusCode, body }` where `body` is a JSON string.
 
-Calls from the app must carry the `X-Project-Token` header; the token is already in
-the app environment as `VITE_XFLOW_PROJECT_TOKEN`. Treat a function as a public API:
-that token ships inside the frontend bundle.
+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
+output of that call. Only failed calls are logged, so an empty output means the function
+never crashed, not that logging is broken.
+
+From the app, call a function through `src/lib/xflow.ts`:
+`await xflow.functions.invoke('send-mail', { body: { to } })`. It carries the project
+token for you. Addresses are baked into the build: the CLI writes them to `.env` when
+you deploy a function, so a frontend built before the function existed cannot see it,
+and needs `xflow deploy` again.
+
+Treat a function as a public API: the token ships inside the frontend bundle, so anyone
+who opens the app can call it.
 
 Organization secrets reach a function only if it mentions them via `process.env`, so
 read them by name and do not build variable names dynamically.
 
+To run a function on a timer: `xflow schedules set report "0 3 ? * * *"` (daily at 03:00).
+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.
+
+## Database
+
+Schema changes are files: `migrations/0001_init.sql`, `migrations/0002_orders.sql`, applied
+in filename order by `xflow db migrate`. `xflow db status` shows what is applied and what
+waits. History lives in the database itself, so an already applied file is never re-run and
+editing it changes nothing: write a new migration instead.
+
+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.
+
+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.
+
 ## Syncing code
 
 `xflow status` shows how the local copy differs from the server revision.
@@ -89,9 +120,13 @@ list of organization members: that is what `user-picker` is built on.
 
 ## Errors from a deployed app
 
-Client-side failures on deployed addresses show up in the platform: open the project,
-section «Облако» (Cloud), tab «Логи» (Logs). Unhandled errors, rejected promises and
-5xx responses land there. The last 200 records per project are kept.
+`xflow logs` prints what broke in the browser on deployed addresses: unhandled errors,
+rejected promises and 5xx responses. The same stream, functions included, is in the
+platform UI: open the project, section «Облако» (Cloud), tab «Логи» (Logs). The last 200
+records per project are kept.
+
+Local `npm run dev` does not report anything: these logs exist for what you cannot open
+in your own devtools.
 
 ## Environment