@getxflow/cli 0.1.1 → 0.1.4

package/README.md

@@ -20,8 +20,10 @@ 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,8 +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");
@@ -82,6 +84,30 @@ async function run(args) {
         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,6 +1,7 @@
 "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");
@@ -10,6 +11,7 @@ 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'];
 /** Папка с функциями внутри проекта. Та же, что была до пивота: менять её незачем. */
@@ -79,6 +81,26 @@ 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 {
@@ -160,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

@@ -34,7 +34,7 @@ function render(rows) {
             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)((0, ui_1.dim)(`    … ещё строк: ${lines.length - STACK_MAX_LINES}`));
         }
         (0, ui_1.out)('');
     }

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,154 +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 [имя]    собрать и выкатить функцию
-  xflow functions invoke <имя> [--data '{"a":1}']
-                                  вызвать функцию и показать ответ
-  xflow functions logs [имя]      падения функций: стек и вывод консоли
-
-${(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
-
+    (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 = {
-    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')} шаблона и только с
+    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')} сюда не пишет.`,
-    invoke: `${(0, ui_1.bold)('xflow functions invoke')} <имя> — вызвать функцию
-
-Вызывает так же, как её вызывает приложение: с заголовком X-Project-Token.
-Токен берётся из карточки проекта на платформе, локальный .env не нужен.
-
-  --data '{"a":1}'   тело запроса (по умолчанию метод становится POST)
-  --method GET       другой метод
-
-Печатает статус, время ответа и тело. Ненулевой код возврата на статусе 4xx и
-5xx: в CI такой вызов должен ронять шаг. Причину падения показывает
+    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')} команда не трогает: это ваши файлы, в них ваши правила.
-Наше знание живёт в своей папке и переустанавливается поверх без спора за файл.
-
+    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.1';
+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.1",
+  "version": "0.1.4",
   "description": "CLI платформы XFlow: синхронизация кода, деплой и публикация приложений",
   "license": "UNLICENSED",
   "engines": {

package/skills/xflow/SKILL.md

@@ -49,13 +49,38 @@ and `xflow functions logs <name>` shows the failures, each with its stack and th
 output of that call. Only failed calls are logged, so an empty output means the function
 never crashed, not that logging is broken.
 
-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.
+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.