@getxflow/cli 0.1.9 → 0.2.0

package/dist/template.js

@@ -7,31 +7,31 @@ 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/
-.env
-.env.*
+const GITIGNORE = `node_modules/
+dist/
+.xflow/
+.env
+.env.*
 `;
-const README = `# %NAME%
-
-An application on XFlow.
-
-\`\`\`bash
-npm install       # dependencies
-npm run dev       # develop on localhost:3000
-xflow deploy      # send the code and build it on the platform
-xflow publish     # show the dev version to visitors
-\`\`\`
-
-The interface is built on the template components: \`src/components/ui\` (buttons, fields,
-dialogs) and \`src/components/blocks\` (table, form, filters, kanban, charts). Layout built
-on top of them looks like the rest of the platform, while custom colors in place of the
-tokens from \`src/index.css\` break that consistency.
-
-Useful: \`xflow status\` for what is on the server, \`xflow deployments\` for version history.
+const README = `# %NAME%
+
+An application on XFlow.
+
+\`\`\`bash
+npm install       # dependencies
+npm run dev       # develop on localhost:3000
+xflow deploy      # send the code and build it on the platform
+xflow publish     # show the dev version to visitors
+\`\`\`
+
+The interface is built on the template components: \`src/components/ui\` (buttons, fields,
+dialogs) and \`src/components/blocks\` (table, form, filters, kanban, charts). Layout built
+on top of them looks like the rest of the platform, while custom colors in place of the
+tokens from \`src/index.css\` break that consistency.
+
+Useful: \`xflow status\` for what is on the server, \`xflow deployments\` for version history.
 `;
-/** Адреса облачных функций для сборки: имя → URL, одной строкой JSON. */
+/** Function name → URL map, one JSON line. */
 exports.FUNCTIONS_ENV_KEY = 'VITE_XFLOW_FUNCTIONS';
 function functionsEnvValue(functions) {
     const map = {};
@@ -41,10 +41,7 @@ function functionsEnvValue(functions) {
     }
     return JSON.stringify(map);
 }
-/**
- * `.env` в исходники не уходит (его пропускают и push, и сервер), поэтому в свежем
- * клоне его восстанавливает `xflow link`.
- */
+/** .env is never pushed; xflow link recreates it in a fresh clone. */
 function envFile(projectToken, apiUrl, functions = []) {
     return [
         `VITE_XFLOW_PROJECT_TOKEN=${projectToken}`,
@@ -53,12 +50,7 @@ function envFile(projectToken, apiUrl, functions = []) {
         '',
     ].join('\n');
 }
-/**
- * Обновить одну переменную в `.env`, не трогая остальные.
- *
- * Файл наш, но живёт у разработчика: рядом с нашими тремя строками у него может
- * лежать что угодно своё, и переписывать файл целиком мы не вправе.
- */
+/** Update one variable in .env without touching the rest of the file. */
 function writeEnvValue(root, key, value) {
     const path = (0, node_path_1.join)(root, '.env');
     const line = `${key}=${value}`;

package/dist/tree.js

@@ -7,12 +7,7 @@ exports.heaviest = heaviest;
 const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
-/**
- * Не отправляется никогда. Первые пять сервер отклоняет и сам, но узнать об
- * этом лучше до заливки 200 МБ node_modules. Секреты (`.env*`) шире серверного
- * списка сознательно: значения переменных живут в настройках организации,
- * а не в репозитории.
- */
+/** Never sent. */
 const DEFAULT_IGNORE = [
     'node_modules/',
     '.git/',
@@ -60,7 +55,7 @@ function compileRule(raw) {
     const suffix = dirOnly ? '/' : '($|/)';
     return { re: new RegExp(`${prefix}${source}${suffix}`) };
 }
-/** Правила исключения: умолчания, файл .xflowignore и поле ignore в xflow.json. */
+/** Defaults, the .xflowignore file and the ignore field of xflow.json. */
 function loadIgnoreRules(root, extra = []) {
     const lines = [...DEFAULT_IGNORE, ...extra];
     const ignoreFile = (0, node_path_1.join)(root, IGNORE_FILE);
@@ -73,7 +68,7 @@ function isIgnored(relativePath, rules, isDirectory) {
     const probe = isDirectory ? `${relativePath}/` : relativePath;
     return rules.some((rule) => rule.re.test(probe));
 }
-/** Двоичный файл: ищем нулевой байт в начале, как это делает git. */
+/** NUL byte in the head, same heuristic as git. */
 function isBinary(content) {
     const limit = Math.min(content.length, 8000);
     for (let i = 0; i < limit; i++) {
@@ -82,12 +77,7 @@ function isBinary(content) {
     }
     return false;
 }
-/**
- * Приводим переводы строк к LF.
- *
- * Иначе одно и то же дерево на Windows и на Linux даёт разные хеши, и статус
- * вечно показывает изменения, которых никто не делал. Двоичные файлы не трогаем.
- */
+/** CRLF and LF must hash the same on every OS. Binary files stay untouched. */
 function normalizeEol(content) {
     if (isBinary(content) || !content.includes(0x0d))
         return content;
@@ -100,8 +90,6 @@ function collectFiles(root, rules) {
         for (const entry of (0, node_fs_1.readdirSync)(dir, { withFileTypes: true })) {
             const full = (0, node_path_1.join)(dir, entry.name);
             const rel = (0, node_path_1.relative)(root, full).split(node_path_1.sep).join('/');
-            // Ссылки не отправляем: в архиве их не представить, а пойти по ним значит
-            // утащить чужое дерево целиком.
             if (entry.isSymbolicLink()) {
                 skippedLinks.push(rel);
                 continue;
@@ -123,13 +111,12 @@ function collectFiles(root, rules) {
     files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
     return { files, skippedLinks };
 }
-/** Хеш дерева. Считается ровно так же на сервере — иначе push «менялось/не менялось» врал бы. */
+/** Computed identically on the server. */
 function treeHash(files) {
     const parts = files.map((file) => `${file.path}\0${(0, node_crypto_1.createHash)('sha256').update(file.content).digest('hex')}`);
     parts.sort();
     return (0, node_crypto_1.createHash)('sha256').update(parts.join('\n')).digest('hex');
 }
-/** Самые тяжёлые файлы: показываем их, когда архив не влез в лимит. */
 function heaviest(files, count = 5) {
     return [...files].sort((a, b) => b.content.length - a.content.length).slice(0, count);
 }

package/dist/types.js

@@ -1,10 +1,3 @@
 "use strict";
-/**
- * Ответы публичного API, которые разбирает CLI.
- *
- * Адресов собранного приложения здесь нет: платформа их наружу не отдаёт. В них
- * зашит номер версии, и после следующей публикации такая ссылка продолжает
- * отвечать старой копией, а не ломается. Версии называем номерами, ссылка одна
- * и ведёт на страницу проекта.
- */
+/** Public API responses parsed by the CLI. */
 Object.defineProperty(exports, "__esModule", { value: true });

package/dist/ui.js

@@ -10,14 +10,13 @@ exports.fail = fail;
 exports.table = table;
 exports.formatBytes = formatBytes;
 exports.formatAge = formatAge;
+exports.offerBrowser = offerBrowser;
 exports.confirmWord = confirmWord;
+const node_child_process_1 = require("node:child_process");
 const node_readline_1 = require("node:readline");
 /**
- * Вывод CLI.
- *
- * Всё пишется через один модуль, а не через console: человек читает stdout,
- * машина парсит его же, а служебные сообщения (шаги, предупреждения) обязаны
- * уходить в stderr, иначе `xflow pull > file` сложит их в файл вместе с данными.
+ * All CLI output. Data goes to stdout, progress and warnings to stderr,
+ * so `xflow pull > file` captures data only.
  */
 const color = process.stdout.isTTY === true && !process.env.NO_COLOR;
 function paint(code, text) {
@@ -30,11 +29,9 @@ exports.dim = dim;
 const red = (t) => paint('31', t);
 const green = (t) => paint('32', t);
 const yellow = (t) => paint('33', t);
-/** Данные: то, ради чего команду запускали. */
 function out(line = '') {
     process.stdout.write(`${line}\n`);
 }
-/** Ход работы: шаги, предупреждения, ошибки. */
 function note(line = '') {
     process.stderr.write(`${line}\n`);
 }
@@ -50,7 +47,7 @@ function warn(message) {
 function fail(message) {
     note(red(`✗ ${message}`));
 }
-/** Таблица с выравниванием по колонкам. Заголовок не рисуем: он не нужен на 3 строки. */
+/** Column-aligned rows, no header. */
 function table(rows) {
     if (rows.length === 0)
         return;
@@ -87,17 +84,42 @@ function formatAge(iso) {
         return `${hours} h ago`;
     return `${Math.floor(hours / 24)} d ago`;
 }
+/** Open a link with the system handler. Failures are ignored: the link is already printed. */
+function openUrl(url) {
+    // The URL reaches a shell on Windows: allow only plain http(s) links.
+    if (!/^https?:\/\/[A-Za-z0-9.-]+(:\d+)?(\/[A-Za-z0-9._~/?=#-]*)?$/.test(url))
+        return;
+    const [command, args] = process.platform === 'win32'
+        ? ['cmd', ['/c', 'start', '', url]]
+        : process.platform === 'darwin'
+            ? ['open', [url]]
+            : ['xdg-open', [url]];
+    try {
+        (0, node_child_process_1.spawn)(command, args, { stdio: 'ignore', detached: true }).unref();
+    }
+    catch {
+        // No browser at all (ssh session): the user opens the link elsewhere.
+    }
+}
 /**
- * Подтверждение опасного действия.
- *
- * Требуем ввести конкретное слово, а не «y»: `--force` перетирает чужую работу,
- * и подтверждение должно стоить осознанного действия. В неинтерактивном режиме
- * (CI, запуск из агента) подтвердить нельзя вовсе — это сознательно (D23).
+ * Offer to open the link on Enter. TTY only, so agent-driven runs are unaffected.
+ * Non-blocking: polling continues, Enter is just a shortcut. Returns a cleanup.
  */
+function offerBrowser(url) {
+    if (!process.stdin.isTTY)
+        return () => { };
+    const rl = (0, node_readline_1.createInterface)({ input: process.stdin, output: process.stderr });
+    rl.on('line', () => {
+        openUrl(url);
+        rl.close();
+    });
+    return () => rl.close();
+}
+/** Dangerous-action confirmation: type the exact word. Unavailable without a TTY. */
 async function confirmWord(question, expected) {
     if (!process.stdin.isTTY) {
         fail('Confirmation is only possible in an interactive terminal');
-        note((0, exports.dim)('  In CI this is the right behaviour: a version conflict has to fail the build rather than overwrite somebody else"s work'));
+        note((0, exports.dim)('  In CI this is the right behaviour: a version conflict has to fail the build rather than overwrite work that is not yours'));
         return false;
     }
     const rl = (0, node_readline_1.createInterface)({ input: process.stdin, output: process.stderr });

package/dist/version.js

@@ -1,11 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_API_URL = exports.CLI_VERSION = void 0;
-/**
- * Версия CLI. Держать синхронно с cli/package.json: читать package.json в
- * рантайме нельзя, после сборки он лежит на уровень выше dist и в бандл не
- * попадает.
- */
-exports.CLI_VERSION = '0.1.9';
-/** Адрес платформы по умолчанию. Переопределяется XFLOW_API_URL и полем `api` в xflow.json. */
+/** Keep in sync with cli/package.json. */
+exports.CLI_VERSION = '0.2.0';
+/** Overridden by XFLOW_API_URL or the `api` field in xflow.json. */
 exports.DEFAULT_API_URL = 'https://app.getxflow.com';

package/dist/zip.js

@@ -10,9 +10,8 @@ exports.ZipError = ZipError;
 const LOCAL_SIG = 0x04034b50;
 const CENTRAL_SIG = 0x02014b50;
 const EOCD_SIG = 0x06054b50;
-/** Флаг «имена в UTF-8»: без него кириллица в путях читается как мохибейк. */
 const FLAG_UTF8 = 0x0800;
-/** 1980-01-01 в формате DOS: время сборки в архив не пишем, чтобы он был воспроизводим. */
+/** Fixed timestamp keeps archives reproducible. */
 const DOS_DATE = 0x0021;
 const DOS_TIME = 0x0000;
 const CRC_TABLE = (() => {
@@ -47,13 +46,11 @@ function zipCreate(entries) {
     const locals = [];
     const centrals = [];
     let offset = 0;
-    // Порядок фиксируем: одно и то же дерево должно давать один и тот же архив.
+    // Same tree, same archive: fixed order.
     const sorted = [...entries].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
     for (const entry of sorted) {
         const name = Buffer.from(entry.path, 'utf-8');
         const crc = crc32(entry.content);
-        // Сжимаем, но только если это что-то даёт: у уже сжатых файлов (png, zip)
-        // deflate добавляет байты, и хранение как есть честнее.
         const deflated = (0, node_zlib_1.deflateRawSync)(entry.content, { level: 6 });
         const compressed = deflated.length < entry.content.length;
         const method = compressed ? 8 : 0;
@@ -110,7 +107,7 @@ function zipCreate(entries) {
     return Buffer.concat([...locals, central, eocd]);
 }
 function findEocd(buffer) {
-    // Комментарий архива может занимать до 64 КБ, поэтому ищем сигнатуру с конца.
+    // The archive comment can be up to 64 KB long: scan from the end.
     const from = Math.max(0, buffer.length - 66_000);
     for (let i = buffer.length - 22; i >= from; i--) {
         if (buffer.readUInt32LE(i) === EOCD_SIG)
@@ -118,6 +115,13 @@ function findEocd(buffer) {
     }
     return -1;
 }
+/** Entries are written to disk by the caller: reject paths that escape the target. */
+function isSafeEntryPath(path) {
+    if (path.length === 0 || path.startsWith('/') || /^[A-Za-z]:/.test(path) || path.includes('\0')) {
+        return false;
+    }
+    return path.split('/').every((part) => part !== '' && part !== '.' && part !== '..');
+}
 function zipRead(buffer) {
     if (buffer.length < 22)
         throw new ZipError('The file is too small to be a zip');
@@ -145,7 +149,7 @@ function zipRead(buffer) {
         if (compressedSize === 0xffffffff || uncompressedSize === 0xffffffff) {
             throw new ZipError(`The zip64 format is not supported: ${name}`);
         }
-        if (buffer.readUInt32LE(localOffset) !== LOCAL_SIG) {
+        if (localOffset + 30 > buffer.length || buffer.readUInt32LE(localOffset) !== LOCAL_SIG) {
             throw new ZipError(`A damaged archive entry: ${name}`);
         }
         const localNameLength = buffer.readUInt16LE(localOffset + 26);
@@ -167,7 +171,10 @@ function zipRead(buffer) {
         else {
             throw new ZipError(`Unknown compression method (${method}) on ${name}`);
         }
-        entries.push({ path: name.replace(/\\/g, '/'), content });
+        const path = name.replace(/\\/g, '/');
+        if (!isSafeEntryPath(path))
+            throw new ZipError(`Unsafe path in the archive: ${name}`);
+        entries.push({ path, content });
     }
     return entries;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getxflow/cli",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "description": "CLI for the XFlow platform: source sync, deployment and publishing of applications",
   "license": "UNLICENSED",
   "engines": {

package/skills/xflow/SKILL.md

@@ -40,8 +40,8 @@ restored within an hour of the data going back under the limit.
 2. `npm run typecheck` for a two-second type check (older projects may not have the
    script, then `npx tsc --noEmit`).
 3. `npm run build` if the change is substantial, before deploying.
-4. `xflow deploy` sends the sources and builds them on the platform, printing each
-   phase and the six-digit number of the version it built.
+4. `xflow deploy` sends the sources, ships the cloud functions and builds the application
+   on the platform, printing each phase and the six-digit number of the version it built.
 5. Give the user the project link the CLI printed and let them look. Do not open a
    browser for them.
 6. `xflow publish` makes that same version visible to visitors.
@@ -105,11 +105,16 @@ Interface rules, checked outside `src/components/ui` and `src/components/blocks`
 
 ## Cloud functions
 
-Server-side code lives in `functions/<name>/index.ts` and exports `handler`. Deploy it
-with `xflow functions deploy` (one name to deploy a single function, no name for all),
-list what is live with `xflow functions list`. The handler returns
+Server-side code lives in `functions/<name>/index.ts` and exports `handler`. There is no
+separate deploy command: `xflow deploy` ships the functions and then builds the application,
+in that order. List what is live with `xflow functions list`. The handler returns
 `{ statusCode, body }` where `body` is a JSON string.
 
+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
+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.
+
 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
@@ -118,9 +123,9 @@ 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.
+token for you. Addresses are baked into the build, which is why the functions go out first:
+by the time the bundle is built they already exist, and a new function is never missing
+from the application that calls it.
 
 Treat a function as a public API: the token ships inside the frontend bundle, so anyone
 who opens the app can call it.
@@ -131,8 +136,8 @@ functions read but the platform does not have. Values never come back out — th
 they exist is inside the running function.
 
 A function receives only the variables it mentions by name via `process.env.NAME`, so never
-assemble a variable name from an expression. New values arrive on the next
-`xflow functions deploy`, not at the moment they are written.
+assemble a variable name from an expression. New values arrive on the next `xflow deploy`,
+not at the moment they are written.
 
 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
@@ -184,12 +189,12 @@ 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 and deploying functions stay in
-the CLI (`xflow push`, `xflow functions deploy`): 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. A build takes minutes, so
-never expect the starting call to return a finished version.
+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.
 
 ## Do not