@getxflow/cli 0.1.4 → 0.1.7

package/skills/xflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: xflow
-description: Build, deploy and publish apps on the XFlow platform with the xflow CLI. Use when the project root has xflow.json or VITE_XFLOW_* variables, when asked to deploy, publish, roll back a version, sync sources with the platform, look into errors from a deployed app, or build UI on the platform design system.
+description: Build, deploy and publish apps on the XFlow platform with the xflow CLI. Use whenever the project root has xflow.json or VITE_XFLOW_* variables, and for any task that touches deployment, publishing, rollback, source sync, the project database or SQL migrations, cloud functions, schedules, environment variables and secrets, production errors and logs, or UI built on the platform design system.
 ---
 
 # XFlow
@@ -22,19 +22,68 @@ contains the fix. Help output is in Russian.
 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, builds locally, uploads the version. It prints
-   a URL: that is the dev address, visible to the team, not to visitors.
-5. Open and check it: the URL from the output, or `xflow open`.
+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.
+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.
 
 The split is deliberate: shipping a build and showing it are two separate decisions.
 Until `publish` runs, visitors keep seeing the previous version.
 
 Rolling back: `xflow deployments` lists the version history, `xflow rollback <id>`
-points the dev address back at an earlier build. Sources stay on their own revision.
-
-The build runs on the developer machine. The platform has no builder, it serves
-static files: a build without `index.html` in the root is rejected.
+points the project back at an earlier build. Sources stay on their own revision.
+
+**The only link you give a person is the project page**, `https://app.getxflow.com/projects/<id>`,
+which the CLI prints for you. Refer to builds by their number ("version 481203 is built,
+092399 is what visitors see"), never by address. The platform does not hand out build
+addresses and neither should you: a build address has the version number baked into it,
+and after the next publish it does not break, it keeps answering with the old copy. Anyone
+holding that link then stares at a frozen app and concludes the changes never shipped. The
+project page always shows the current state, and every version is reachable from it.
+
+The platform builds the project itself, in a clean sandbox with one Node version for
+everyone, and serves the result as static files. Nothing is built on your machine for
+deployment, so a local `npm run build` is only a fast way to see errors early.
+
+## Build gate
+
+Before the sandbox starts, the platform checks the sources against the template. Every
+rule below blocks the build, and the whole list of violations comes back at once, with
+files and line numbers. Nothing is charged for a rejected attempt: the sandbox never
+starts. Write code that already satisfies these rules instead of learning them from
+rejections.
+
+Build setup:
+
+- `package.json` with the build script named in `xflow.json` (`npm run build` by default).
+- Vite: a `vite.config.*` and `vite` in dependencies.
+- No server frameworks: `next`, `nuxt`, `remix`, `@sveltejs/kit`, `astro`.
+- `index.html` in the root, `src/main.tsx` as the entry point.
+- Application code under `src/`. Root `app/`, `pages/`, `next/` are rejected.
+
+Platform contract, checked across all of `src/`:
+
+- Call cloud functions through `xflow.functions.invoke`, never through a hardcoded
+  `*.yandexcloud.net` URL: the address changes and the app breaks silently.
+- No API keys or tokens in the source: they end up in the bundle. Put the call in a
+  cloud function and the key in project secrets.
+- No server modules (`fs`, `express`, `http`, `child_process`): there is no server runtime.
+
+Interface rules, checked outside `src/components/ui` and `src/components/blocks`:
+
+- No `alert()`, `confirm()`, `prompt()`. Use the Dialog and Toast components.
+- No `console.log`. Deployed apps have a public console, and forgotten debugging prints
+  user data into it. `console.error` and `console.warn` are fine, they reach the project
+  logs.
+- No inline styles with literal values (`style={{ color: '#fff' }}`). Computed styles
+  (a drag transform, a progress width) are fine, Tailwind cannot express them.
+- No hex colors or Tailwind palette classes (`text-gray-500`): use the theme tokens.
+  Charts are exempt, they need real colors.
+- No importing a `@/components/ui/*` component that does not exist in the project.
+- A library that needs a provider (`@tanstack/react-query`, `react-redux`, `sonner`,
+  `react-hot-toast`, `react-dnd`) must have it mounted in `App.tsx`. Missing providers
+  build fine and give visitors a white screen.
 
 ## Cloud functions
 
@@ -58,8 +107,14 @@ 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.
+Keys and passwords live on the platform, not in the repository: `xflow env set SMTP_PASSWORD=…`
+writes one, `xflow env` lists the names, `xflow env check` tells you which variables your
+functions read but the platform does not have. Values never come back out — the only place
+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.
 
 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
@@ -72,6 +127,18 @@ in filename order by `xflow db migrate`. `xflow db status` shows what is applied
 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 browser never reaches the database directly. The app reads and writes through a cloud
+function, and inside the handler the connection string is already there:
+
+```js
+const { Client } = require('pg')
+const db = new Client({ connectionString: process.env.DATABASE_URL })
+```
+
+The platform passes `DATABASE_URL` only to functions that mention it, and sets the project
+schema on every connection, so plain table names (`select * from tasks`) hit your project.
+You never write that variable yourself: `xflow env set DATABASE_URL=...` is refused.
+
 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
@@ -91,6 +158,21 @@ Fetch their work next to yours (`xflow pull --into ./server-copy`), merge it loc
 then push again. `--force` destroys their work: a last resort, not a way around the
 error.
 
+## Direct access without the terminal
+
+The platform also exposes an MCP server, connected with `xflow mcp install`. When its tools
+are available, prefer them for control-plane work: project state, database schema and
+read-only queries, migrations, function logs and invocations, schedules, environment
+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.
+
 ## Do not
 
 - Edit `xflow.json` by hand: the CLI writes it.

package/dist/open-url.js

@@ -1,24 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.openUrl = openUrl;
-const node_child_process_1 = require("node:child_process");
-/**
- * Открыть адрес в браузере пользователя.
- *
- * Best-effort: на сервере без графики открывать нечего, и это не ошибка —
- * вызывающий в любом случае печатает ссылку рядом.
- */
-function openUrl(url) {
-    try {
-        const command = process.platform === 'win32' ? 'cmd' : process.platform === 'darwin' ? 'open' : 'xdg-open';
-        const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
-        const child = (0, node_child_process_1.spawn)(command, args, { stdio: 'ignore', detached: true });
-        child.on('error', () => {
-            // Браузера нет — молча, ссылка уже показана.
-        });
-        child.unref();
-    }
-    catch {
-        // То же самое: открыть не удалось, но команда не про это.
-    }
-}