@getxflow/cli 1.0.3 → 1.0.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/commands/skills.js +5 -0
- package/dist/tree.js +5 -1
- package/dist/version.js +1 -1
- package/package.json +24 -24
- package/skills/xflow/SKILL.md +706 -708
package/skills/xflow/SKILL.md
CHANGED
|
@@ -1,708 +1,706 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: xflow
|
|
3
|
-
description: Build, deploy and publish apps on the XFlow platform with the xflow CLI. Use whenever a folder has xflow.json (the project root or an app folder in apps/), and for any task that touches a project and its apps, deployment, publishing, rollback, source sync, who may open an app or call a function, sign-in inside a public app, the project database or SQL migrations, cloud functions, schedules, environment variables and secrets, file storage and uploads of photos, video or PDFs, connected accounts of external services, production errors and logs, UI built on the template components, or a public page on xflowpage.ru (a landing page, presentation or invoice for people outside the organization).
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# XFlow
|
|
7
|
-
|
|
8
|
-
Hosting for web apps. The code lives in an ordinary repository on the developer machine, the
|
|
9
|
-
CLI sends the sources, the platform builds them in a clean sandbox, serves each app at its own
|
|
10
|
-
address and runs its backend: one database and cloud functions per project.
|
|
11
|
-
|
|
12
|
-
No `xflow.json` in the folder or above it means it is not bound to a project yet:
|
|
13
|
-
`xflow projects list` names the projects of the organization with their ids, `xflow link <id>`
|
|
14
|
-
binds the folder to one (an empty folder gets the whole project), and `xflow init` starts a new
|
|
15
|
-
project with its first app.
|
|
16
|
-
|
|
17
|
-
## First rule
|
|
18
|
-
|
|
19
|
-
Check commands and flags against `xflow help` and `xflow help <command>`, not against
|
|
20
|
-
memory. If a command is not in the help output, it does not exist: guessing flags is
|
|
21
|
-
pointless. The CLI prints a hint with almost every error, read it in full, it usually
|
|
22
|
-
contains the fix.
|
|
23
|
-
|
|
24
|
-
## Keeping these instructions current
|
|
25
|
-
|
|
26
|
-
These instructions ship with xflow CLI 1.0.
|
|
27
|
-
the CLI answering your commands.
|
|
28
|
-
|
|
29
|
-
When the CLI says this file does not match it, run `xflow skills --refresh` and then **read
|
|
30
|
-
again the file it names**: refreshing only writes to disk, and until you re-read it you are
|
|
31
|
-
still working from the old rules. Do it yourself, no need to ask.
|
|
32
|
-
|
|
33
|
-
Updating the CLI is not yours. `xflow update` replaces a program shared by every project on
|
|
34
|
-
the machine: offer the update in your summary. The exception is a platform refusing the CLI as too old (`outdated_cli`):
|
|
35
|
-
nothing runs until it is updated, so say what you are doing and run it.
|
|
36
|
-
|
|
37
|
-
## Hard rules
|
|
38
|
-
|
|
39
|
-
These mistakes cost the most because nothing fails at the moment they are made, or
|
|
40
|
-
the error points away from the cause. The sections below carry the details.
|
|
41
|
-
|
|
42
|
-
1. Read environment variables literally: `process.env.API_KEY`. Destructuring
|
|
43
|
-
(`const { API_KEY } = process.env`), a name built from an expression, `?.` and
|
|
44
|
-
spreading the environment all read as no mention of the variable at all. The
|
|
45
|
-
build rejects them, and `xflow env check` names them before that.
|
|
46
|
-
2. A value written with `xflow env set` reaches the functions on the next
|
|
47
|
-
`xflow deploy functions`, not at the moment it is written.
|
|
48
|
-
3. Never delete a `functions/<name>/` directory unless the user asked for that
|
|
49
|
-
function to go. The next deploy removes it from the cloud together with its keys and
|
|
50
|
-
schedules, and that is final.
|
|
51
|
-
4. A function an app or a page calls needs that caller in its `callers` in the root
|
|
52
|
-
`xflow.json`. Without it the call answers 404 `not_bound`, and a new function is not
|
|
53
|
-
reachable from anywhere.
|
|
54
|
-
5. Every function with a public caller (a page, an app open to anyone) can be called by
|
|
55
|
-
anybody on the internet with curl. Write it as such, see **Your function is open to the
|
|
56
|
-
whole internet**.
|
|
57
|
-
6. An already applied migration is never re-run, and `xflow db migrate` refuses a
|
|
58
|
-
name it already holds with different content. A schema change is always a new file.
|
|
59
|
-
7. When `xflow db migrate` answers `db_write_locked`, or an INSERT or CREATE TABLE in a
|
|
60
|
-
function fails with `permission denied` (42501), the database is over its plan size and
|
|
61
|
-
Postgres itself refuses. Reads, updates and deletes keep working, so the fix is a migration
|
|
62
|
-
that deletes data, never a rewrite of the SQL. Write comes back within the hour.
|
|
63
|
-
8. Heavy media does not travel with the sources. Photos, video and PDFs go up with
|
|
64
|
-
`xflow storage push`, not into the repository: the archive is capped at 10 MB.
|
|
65
|
-
|
|
66
|
-
## Projects and apps
|
|
67
|
-
|
|
68
|
-
- A project is a box: one database with its migrations, the cloud functions, secrets and
|
|
69
|
-
members. It has no code of its own.
|
|
70
|
-
- An app is code the platform builds and serves at `https://<id>--<org>.xflowpage.ru`
|
|
71
|
-
(`<id>` is six random characters the platform gives the app, `<org>` the name of the
|
|
72
|
-
organization): its own versions, its own access level. A project holds one or more apps,
|
|
73
|
-
and all of them use the same database and the same functions.
|
|
74
|
-
- A project without apps is fine (`xflow init --no-app`): its functions are workflows, woken
|
|
75
|
-
by a schedule, by an outside service holding a key, or by `xflow functions invoke`.
|
|
76
|
-
- `xflow projects get` shows the apps with their folders, addresses and access levels, and
|
|
77
|
-
who may call each function.
|
|
78
|
-
|
|
79
|
-
## Folder layout
|
|
80
|
-
|
|
81
|
-
One folder per project, apps in subfolders:
|
|
82
|
-
|
|
83
|
-
clinic/
|
|
84
|
-
xflow.json projectId, and who may call each function
|
|
85
|
-
package.json dependencies of the functions
|
|
86
|
-
functions/<name>/index.ts cloud functions, shared by every app
|
|
87
|
-
migrations/0001_init.sql the one database of the project
|
|
88
|
-
apps/
|
|
89
|
-
priem/ an app: a Vite project with its own xflow.json (appId, build)
|
|
90
|
-
zapis/
|
|
91
|
-
|
|
92
|
-
- Two kinds of history: the project root (functions, migrations, `xflow.json`) is one, each
|
|
93
|
-
app is another. `apps/**` never travels with the root, the root never travels with an app.
|
|
94
|
-
- An app sees only its own folder when it is built. What two apps share is data and logic,
|
|
95
|
-
and that lives in functions. Functions never go inside an app folder: the build refuses
|
|
96
|
-
`functions/` there (`functions-in-app`).
|
|
97
|
-
- `xflow apps add <folder>` creates an app, lays the template into `apps/<folder>` and prints
|
|
98
|
-
its address. Never create an app folder by hand: without its `appId` it is nobody's.
|
|
99
|
-
`--color <color>` sets the tile the user sees in the project; a wrong one is answered with
|
|
100
|
-
the list of colors. Its icon and a later color change belong to the person in the web
|
|
101
|
-
interface.
|
|
102
|
-
- Rename an app folder freely: the app is its `appId`.
|
|
103
|
-
- Commands follow the folder you stand in: inside `apps/zapis` they mean that app, anywhere
|
|
104
|
-
else in the project they mean the project. `--project <id>` and `--app <id>` name them
|
|
105
|
-
without a folder.
|
|
106
|
-
- Neither `xflow.json` is edited by hand except `functions.<name>.callers` in the root one.
|
|
107
|
-
|
|
108
|
-
## Plan limits
|
|
109
|
-
|
|
110
|
-
The organization runs on a plan with limits: apps, functions, pages, active connections,
|
|
111
|
-
people in the organization, database and file storage, function minutes, builds per month and at once, schedules
|
|
112
|
-
and how often they may run, and which access levels an app may have. Most are finite; a plan
|
|
113
|
-
may leave one uncapped, and then `whoami` prints `no limit` instead of a ceiling.
|
|
114
|
-
`xflow whoami` prints every one of them next to what is used, and the rights of your own key
|
|
115
|
-
with them: destroying data in a migration, deleting files from storage, moving a database and
|
|
116
|
-
linking a connected account each need a right. Reading it before a long task turns a refusal
|
|
117
|
-
halfway through the work into a sentence said before it starts.
|
|
118
|
-
|
|
119
|
-
- Connections are counted while active: switching an unused one off frees the seat without
|
|
120
|
-
deleting it.
|
|
121
|
-
- Function minutes are shared by the whole organization: every app, page and schedule spends
|
|
122
|
-
them. When they run out, every function of the organization stops (`functions_stopped`).
|
|
123
|
-
- The cap on how long one function call may run is written into the function when it is
|
|
124
|
-
deployed, so a plan change reaches the cloud only with the next `xflow deploy functions` of
|
|
125
|
-
each project, in both directions.
|
|
126
|
-
|
|
127
|
-
A limit refusal is not a bad request. The CLI prints a line starting with `Plan limit:`, the
|
|
128
|
-
API answers `code: "forbidden"` with a `limit` object (`code`, `used`, `limit`), MCP tools
|
|
129
|
-
carry the same field. Retrying, renaming or rewriting the code changes nothing: tell the user
|
|
130
|
-
what ran out and stop, only the owner lifts it. A schedule refused for running too often is one
|
|
131
|
-
of these too, not a bad cron string: the minimum interval comes from the plan, never guess it.
|
|
132
|
-
|
|
133
|
-
## Deploying
|
|
134
|
-
|
|
135
|
-
1. Change the code. In an app folder `npm run typecheck` is a two-second check, `npm run build`
|
|
136
|
-
a fast way to see build errors early: the platform builds again in its own sandbox.
|
|
137
|
-
2. `xflow db migrate` when the schema changes. It stores the project root first (migrations
|
|
138
|
-
live in its history), then applies what is new.
|
|
139
|
-
3. `xflow deploy functions -m "what changed"` sends the project root, checks it, ships the
|
|
140
|
-
functions and their callers. Every app runs the new code the moment it finishes: there is
|
|
141
|
-
no staging and no publish step for server code. Say so to the user.
|
|
142
|
-
4. `xflow deploy apps/zapis -m "what changed"` sends and builds one app; inside `apps/zapis` a
|
|
143
|
-
plain `xflow deploy` does the same. In the root a plain `xflow deploy` refuses and names the
|
|
144
|
-
targets. The comment is required: one short line in the language the user speaks.
|
|
145
|
-
5. `xflow publish` in the app folder (or with `--app <id>`) shows that build to visitors.
|
|
146
|
-
|
|
147
|
-
A change that touches data and screens goes in this order: the migration, the functions, then
|
|
148
|
-
every app that shows it. `xflow deploy apps/...` warns when the root holds changes nobody
|
|
149
|
-
deployed.
|
|
150
|
-
|
|
151
|
-
- A build of an app is not shown to visitors until `xflow publish`. Publishing points the
|
|
152
|
-
address at a build and takes a second; `xflow publish <number>` (or `xflow rollback <number>`)
|
|
153
|
-
points it at an older kept build, and that is the rollback. The very first build of a new
|
|
154
|
-
app publishes itself.
|
|
155
|
-
- Only the app moves on publish and rollback. Functions come back with
|
|
156
|
-
`xflow deploy functions --revision N -m "why"` (`xflow deployments functions` lists the revisions);
|
|
157
|
-
`--project <id>` names the project without a folder.
|
|
158
|
-
- Files of the **three latest successful builds** of each app are kept, plus the live one;
|
|
159
|
-
`xflow deployments` marks the rest `no pages`. The history keeps 30 builds, a revision stays
|
|
160
|
-
while its build is in it or it is among the 10 latest. Keep anything you must not lose in
|
|
161
|
-
your own git repository.
|
|
162
|
-
- Give a person the app address the CLI printed, or the project page it printed. Name builds
|
|
163
|
-
by their number.
|
|
164
|
-
- `xflow status` says how the local copies differ from the server. A deploy rejected before
|
|
165
|
-
the build starts means the server holds a revision this folder has never seen: fetch it next
|
|
166
|
-
to yours (`xflow pull --into ./server-copy`), merge in git, deploy again. `--force` destroys
|
|
167
|
-
that work. A folder with no record of the server revision (a fresh clone, a CI checkout) is
|
|
168
|
-
not rejected: its first deploy goes on top and says so.
|
|
169
|
-
- A deploy that would delete functions gone from the sources refuses until somebody agrees;
|
|
170
|
-
`--allow-removals` is the only way past it without a terminal. Reaching for it to get a
|
|
171
|
-
build running means you deleted something the user never asked you to: put the directories
|
|
172
|
-
back. If the removal is intended, name the functions and let the user answer.
|
|
173
|
-
|
|
174
|
-
## Build gate
|
|
175
|
-
|
|
176
|
-
Before the sandbox starts, the platform checks the sources. Everything below blocks the build,
|
|
177
|
-
all violations come back together with files and lines, and a rejected attempt costs nothing.
|
|
178
|
-
|
|
179
|
-
An app:
|
|
180
|
-
|
|
181
|
-
- `package.json` with the build script named in its `xflow.json` (`npm run build` by default),
|
|
182
|
-
a `vite.config.*` and `vite` in dependencies. No server frameworks: `next`, `nuxt`, Remix,
|
|
183
|
-
`@sveltejs/kit`, `astro`.
|
|
184
|
-
- `index.html` in the app root with `id="root"` and the script that loads `src/main.tsx`
|
|
185
|
-
(`.ts`, `.jsx`, `.js` count too). Code under `src/`; root `app/`, `pages/`, `next/` are rejected.
|
|
186
|
-
- Keep `base` in `vite.config.js` as the template has it: the platform serves each build from
|
|
187
|
-
`/_b/<key>/`, and a build whose `index.html` points elsewhere is refused.
|
|
188
|
-
- The built app at most 15 MB unpacked, the sources at most 10 MB.
|
|
189
|
-
- File names in latin letters, digits, spaces and `. - _ ~` only: `логотип.png` breaks the build.
|
|
190
|
-
- Call functions through `xflow.functions.invoke`, never a hardcoded function address.
|
|
191
|
-
- No keys or tokens in the sources, no server modules (`fs`, `express`, `http`, `child_process`).
|
|
192
|
-
- Outside `src/components/ui` and `src/components/blocks`: no `alert()`, `confirm()`,
|
|
193
|
-
`prompt()` (use Dialog and Toast), no `console.log` (visitors read the console;
|
|
194
|
-
`console.error` and `console.warn` reach the logs).
|
|
195
|
-
- A library that needs a provider (`@tanstack/react-query`, `react-redux`, `sonner`,
|
|
196
|
-
`react-hot-toast`, `react-dnd`) must have it mounted. A missing provider builds fine and
|
|
197
|
-
gives visitors a white screen.
|
|
198
|
-
- The platform files stay byte for byte as they arrived: `src/lib/platform-auth.ts`,
|
|
199
|
-
`src/contexts/platform-auth-context.tsx`, `src/hooks/use-platform-auth.ts`,
|
|
200
|
-
`src/utils/error-logger.ts`, `src/lib/xflow.ts`. The code keeps calling `initPlatformAuth()`
|
|
201
|
-
and `initErrorLogger()` and importing `index.css`, and the Tailwind
|
|
202
|
-
`content` globs keep covering `src/**`. A rejection names the revision to take the original
|
|
203
|
-
from: `xflow pull --revision N --into ./original`, then copy the file back.
|
|
204
|
-
|
|
205
|
-
The project root: function names are lowercase latin letters, digits and hyphens, up to 41
|
|
206
|
-
characters (`send-mail`, not `sendMail`); every name under `functions` in `xflow.json` has its
|
|
207
|
-
`functions/<name>/index.ts`; every caller is an app folder of this project or an existing page
|
|
208
|
-
of the organization (`unknown-caller`).
|
|
209
|
-
|
|
210
|
-
Passes with a line `Unfinished:` instead of blocking: the template's page title, no
|
|
211
|
-
`<link rel="icon">` in `index.html`, an `exports.access` left in a function (it does nothing).
|
|
212
|
-
Fix the first two before you tell the person the app is done.
|
|
213
|
-
|
|
214
|
-
## The template is a starter kit
|
|
215
|
-
|
|
216
|
-
- `src/components/ui` and `src/components/blocks` are a starting set: change them, restyle them
|
|
217
|
-
or delete what you do not use. Any colors, your own color scheme, inline styles, a single
|
|
218
|
-
theme without dark mode: all allowed.
|
|
219
|
-
- The template looks like the xflow interface: warm grays, hairline controls (`ctl-solid`,
|
|
220
|
-
`ctl-raised`, `ctl-inset`, `ctl-select`), segments (`seg-track`, `seg-on`) and surfaces
|
|
221
|
-
(`surface-raised`, `surface-pop`, `surface-modal`) in `src/index.css`.
|
|
222
|
-
- While any template component is left, the theme token names in `:root` of `src/index.css`
|
|
223
|
-
and their `hsl(var(--name))` mapping in the Tailwind config stay: those components paint with
|
|
224
|
-
them. Values change freely; they are HSL components (`216 95% 40%`), not `#hex`. Your own
|
|
225
|
-
colors go under new names.
|
|
226
|
-
- Images and other assets: import them from `src/` (`import logo from './assets/logo.png'`)
|
|
227
|
-
so the build puts them next to the code. An absolute path into `public/` (`/logo.png`) goes
|
|
228
|
-
through the access check of the app and fails inside the xflow frame in Safari.
|
|
229
|
-
|
|
230
|
-
## Who opens an app
|
|
231
|
-
|
|
232
|
-
A person sets this in the web interface; you cannot, and you should not ask for a way around.
|
|
233
|
-
|
|
234
|
-
| Level | Who gets in |
|
|
235
|
-
|---|---|
|
|
236
|
-
| Project members | people who have access to the project
|
|
237
|
-
| Anyone with the link | anybody, no sign-in at all |
|
|
238
|
-
|
|
239
|
-
- The plan decides which levels exist: on Free an app opens only inside xflow, Start adds the
|
|
240
|
-
direct address
|
|
241
|
-
- At the closed level the platform signs people in, and a function receives the person in
|
|
242
|
-
`event.xflow.user` (`id`, `role` in the organization, `name
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
-
|
|
247
|
-
|
|
248
|
-
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
-
|
|
270
|
-
|
|
271
|
-
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
`
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
-
|
|
294
|
-
|
|
295
|
-
-
|
|
296
|
-
|
|
297
|
-
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
the
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
-
|
|
329
|
-
|
|
330
|
-
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
-
|
|
338
|
-
|
|
339
|
-
-
|
|
340
|
-
|
|
341
|
-
-
|
|
342
|
-
|
|
343
|
-
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
`
|
|
353
|
-
|
|
354
|
-
`
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
//
|
|
392
|
-
//
|
|
393
|
-
//
|
|
394
|
-
//
|
|
395
|
-
//
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
```
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
the
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
xflow connections call
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
in
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
`xflow
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
xflow
|
|
494
|
-
|
|
495
|
-
xflow
|
|
496
|
-
xflow
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
`
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
the
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
|
|
620
|
-
- `xflow pages
|
|
621
|
-
|
|
622
|
-
- `xflow pages
|
|
623
|
-
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
-
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
-
|
|
635
|
-
|
|
636
|
-
-
|
|
637
|
-
-
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
-
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
-
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
-
|
|
684
|
-
|
|
685
|
-
-
|
|
686
|
-
-
|
|
687
|
-
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
`xflow logs` prints
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
For CI and agent runs: `XFLOW_TOKEN` replaces `xflow login`, `XFLOW_API_URL` points at another
|
|
708
|
-
platform host. There is no `.env` from the platform: the bundle carries no tokens or addresses.
|
|
1
|
+
---
|
|
2
|
+
name: xflow
|
|
3
|
+
description: Build, deploy and publish apps on the XFlow platform with the xflow CLI. Use whenever a folder has xflow.json (the project root or an app folder in apps/), and for any task that touches a project and its apps, deployment, publishing, rollback, source sync, who may open an app or call a function, sign-in inside a public app, the project database or SQL migrations, cloud functions, schedules, environment variables and secrets, file storage and uploads of photos, video or PDFs, connected accounts of external services, production errors and logs, UI built on the template components, or a public page on xflowpage.ru (a landing page, presentation or invoice for people outside the organization).
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# XFlow
|
|
7
|
+
|
|
8
|
+
Hosting for web apps. The code lives in an ordinary repository on the developer machine, the
|
|
9
|
+
CLI sends the sources, the platform builds them in a clean sandbox, serves each app at its own
|
|
10
|
+
address and runs its backend: one database and cloud functions per project.
|
|
11
|
+
|
|
12
|
+
No `xflow.json` in the folder or above it means it is not bound to a project yet:
|
|
13
|
+
`xflow projects list` names the projects of the organization with their ids, `xflow link <id>`
|
|
14
|
+
binds the folder to one (an empty folder gets the whole project), and `xflow init` starts a new
|
|
15
|
+
project with its first app.
|
|
16
|
+
|
|
17
|
+
## First rule
|
|
18
|
+
|
|
19
|
+
Check commands and flags against `xflow help` and `xflow help <command>`, not against
|
|
20
|
+
memory. If a command is not in the help output, it does not exist: guessing flags is
|
|
21
|
+
pointless. The CLI prints a hint with almost every error, read it in full, it usually
|
|
22
|
+
contains the fix.
|
|
23
|
+
|
|
24
|
+
## Keeping these instructions current
|
|
25
|
+
|
|
26
|
+
These instructions ship with xflow CLI 1.0.5, so the copy you are reading can be older than
|
|
27
|
+
the CLI answering your commands.
|
|
28
|
+
|
|
29
|
+
When the CLI says this file does not match it, run `xflow skills --refresh` and then **read
|
|
30
|
+
again the file it names**: refreshing only writes to disk, and until you re-read it you are
|
|
31
|
+
still working from the old rules. Do it yourself, no need to ask.
|
|
32
|
+
|
|
33
|
+
Updating the CLI is not yours. `xflow update` replaces a program shared by every project on
|
|
34
|
+
the machine: offer the update in your summary. The exception is a platform refusing the CLI as too old (`outdated_cli`):
|
|
35
|
+
nothing runs until it is updated, so say what you are doing and run it.
|
|
36
|
+
|
|
37
|
+
## Hard rules
|
|
38
|
+
|
|
39
|
+
These mistakes cost the most because nothing fails at the moment they are made, or
|
|
40
|
+
the error points away from the cause. The sections below carry the details.
|
|
41
|
+
|
|
42
|
+
1. Read environment variables literally: `process.env.API_KEY`. Destructuring
|
|
43
|
+
(`const { API_KEY } = process.env`), a name built from an expression, `?.` and
|
|
44
|
+
spreading the environment all read as no mention of the variable at all. The
|
|
45
|
+
build rejects them, and `xflow env check` names them before that.
|
|
46
|
+
2. A value written with `xflow env set` reaches the functions on the next
|
|
47
|
+
`xflow deploy functions`, not at the moment it is written.
|
|
48
|
+
3. Never delete a `functions/<name>/` directory unless the user asked for that
|
|
49
|
+
function to go. The next deploy removes it from the cloud together with its keys and
|
|
50
|
+
schedules, and that is final.
|
|
51
|
+
4. A function an app or a page calls needs that caller in its `callers` in the root
|
|
52
|
+
`xflow.json`. Without it the call answers 404 `not_bound`, and a new function is not
|
|
53
|
+
reachable from anywhere.
|
|
54
|
+
5. Every function with a public caller (a page, an app open to anyone) can be called by
|
|
55
|
+
anybody on the internet with curl. Write it as such, see **Your function is open to the
|
|
56
|
+
whole internet**.
|
|
57
|
+
6. An already applied migration is never re-run, and `xflow db migrate` refuses a
|
|
58
|
+
name it already holds with different content. A schema change is always a new file.
|
|
59
|
+
7. When `xflow db migrate` answers `db_write_locked`, or an INSERT or CREATE TABLE in a
|
|
60
|
+
function fails with `permission denied` (42501), the database is over its plan size and
|
|
61
|
+
Postgres itself refuses. Reads, updates and deletes keep working, so the fix is a migration
|
|
62
|
+
that deletes data, never a rewrite of the SQL. Write comes back within the hour.
|
|
63
|
+
8. Heavy media does not travel with the sources. Photos, video and PDFs go up with
|
|
64
|
+
`xflow storage push`, not into the repository: the archive is capped at 10 MB.
|
|
65
|
+
|
|
66
|
+
## Projects and apps
|
|
67
|
+
|
|
68
|
+
- A project is a box: one database with its migrations, the cloud functions, secrets and
|
|
69
|
+
members. It has no code of its own.
|
|
70
|
+
- An app is code the platform builds and serves at `https://<id>--<org>.xflowpage.ru`
|
|
71
|
+
(`<id>` is six random characters the platform gives the app, `<org>` the name of the
|
|
72
|
+
organization): its own versions, its own access level. A project holds one or more apps,
|
|
73
|
+
and all of them use the same database and the same functions.
|
|
74
|
+
- A project without apps is fine (`xflow init --no-app`): its functions are workflows, woken
|
|
75
|
+
by a schedule, by an outside service holding a key, or by `xflow functions invoke`.
|
|
76
|
+
- `xflow projects get` shows the apps with their folders, addresses and access levels, and
|
|
77
|
+
who may call each function.
|
|
78
|
+
|
|
79
|
+
## Folder layout
|
|
80
|
+
|
|
81
|
+
One folder per project, apps in subfolders:
|
|
82
|
+
|
|
83
|
+
clinic/
|
|
84
|
+
xflow.json projectId, and who may call each function
|
|
85
|
+
package.json dependencies of the functions
|
|
86
|
+
functions/<name>/index.ts cloud functions, shared by every app
|
|
87
|
+
migrations/0001_init.sql the one database of the project
|
|
88
|
+
apps/
|
|
89
|
+
priem/ an app: a Vite project with its own xflow.json (appId, build)
|
|
90
|
+
zapis/
|
|
91
|
+
|
|
92
|
+
- Two kinds of history: the project root (functions, migrations, `xflow.json`) is one, each
|
|
93
|
+
app is another. `apps/**` never travels with the root, the root never travels with an app.
|
|
94
|
+
- An app sees only its own folder when it is built. What two apps share is data and logic,
|
|
95
|
+
and that lives in functions. Functions never go inside an app folder: the build refuses
|
|
96
|
+
`functions/` there (`functions-in-app`).
|
|
97
|
+
- `xflow apps add <folder>` creates an app, lays the template into `apps/<folder>` and prints
|
|
98
|
+
its address. Never create an app folder by hand: without its `appId` it is nobody's.
|
|
99
|
+
`--color <color>` sets the tile the user sees in the project; a wrong one is answered with
|
|
100
|
+
the list of colors. Its icon and a later color change belong to the person in the web
|
|
101
|
+
interface.
|
|
102
|
+
- Rename an app folder freely: the app is its `appId`.
|
|
103
|
+
- Commands follow the folder you stand in: inside `apps/zapis` they mean that app, anywhere
|
|
104
|
+
else in the project they mean the project. `--project <id>` and `--app <id>` name them
|
|
105
|
+
without a folder.
|
|
106
|
+
- Neither `xflow.json` is edited by hand except `functions.<name>.callers` in the root one.
|
|
107
|
+
|
|
108
|
+
## Plan limits
|
|
109
|
+
|
|
110
|
+
The organization runs on a plan with limits: apps, functions, pages, active connections,
|
|
111
|
+
people in the organization, database and file storage, function minutes, builds per month and at once, schedules
|
|
112
|
+
and how often they may run, and which access levels an app may have. Most are finite; a plan
|
|
113
|
+
may leave one uncapped, and then `whoami` prints `no limit` instead of a ceiling.
|
|
114
|
+
`xflow whoami` prints every one of them next to what is used, and the rights of your own key
|
|
115
|
+
with them: destroying data in a migration, deleting files from storage, moving a database and
|
|
116
|
+
linking a connected account each need a right. Reading it before a long task turns a refusal
|
|
117
|
+
halfway through the work into a sentence said before it starts.
|
|
118
|
+
|
|
119
|
+
- Connections are counted while active: switching an unused one off frees the seat without
|
|
120
|
+
deleting it.
|
|
121
|
+
- Function minutes are shared by the whole organization: every app, page and schedule spends
|
|
122
|
+
them. When they run out, every function of the organization stops (`functions_stopped`).
|
|
123
|
+
- The cap on how long one function call may run is written into the function when it is
|
|
124
|
+
deployed, so a plan change reaches the cloud only with the next `xflow deploy functions` of
|
|
125
|
+
each project, in both directions.
|
|
126
|
+
|
|
127
|
+
A limit refusal is not a bad request. The CLI prints a line starting with `Plan limit:`, the
|
|
128
|
+
API answers `code: "forbidden"` with a `limit` object (`code`, `used`, `limit`), MCP tools
|
|
129
|
+
carry the same field. Retrying, renaming or rewriting the code changes nothing: tell the user
|
|
130
|
+
what ran out and stop, only the owner lifts it. A schedule refused for running too often is one
|
|
131
|
+
of these too, not a bad cron string: the minimum interval comes from the plan, never guess it.
|
|
132
|
+
|
|
133
|
+
## Deploying
|
|
134
|
+
|
|
135
|
+
1. Change the code. In an app folder `npm run typecheck` is a two-second check, `npm run build`
|
|
136
|
+
a fast way to see build errors early: the platform builds again in its own sandbox.
|
|
137
|
+
2. `xflow db migrate` when the schema changes. It stores the project root first (migrations
|
|
138
|
+
live in its history), then applies what is new.
|
|
139
|
+
3. `xflow deploy functions -m "what changed"` sends the project root, checks it, ships the
|
|
140
|
+
functions and their callers. Every app runs the new code the moment it finishes: there is
|
|
141
|
+
no staging and no publish step for server code. Say so to the user.
|
|
142
|
+
4. `xflow deploy apps/zapis -m "what changed"` sends and builds one app; inside `apps/zapis` a
|
|
143
|
+
plain `xflow deploy` does the same. In the root a plain `xflow deploy` refuses and names the
|
|
144
|
+
targets. The comment is required: one short line in the language the user speaks.
|
|
145
|
+
5. `xflow publish` in the app folder (or with `--app <id>`) shows that build to visitors.
|
|
146
|
+
|
|
147
|
+
A change that touches data and screens goes in this order: the migration, the functions, then
|
|
148
|
+
every app that shows it. `xflow deploy apps/...` warns when the root holds changes nobody
|
|
149
|
+
deployed.
|
|
150
|
+
|
|
151
|
+
- A build of an app is not shown to visitors until `xflow publish`. Publishing points the
|
|
152
|
+
address at a build and takes a second; `xflow publish <number>` (or `xflow rollback <number>`)
|
|
153
|
+
points it at an older kept build, and that is the rollback. The very first build of a new
|
|
154
|
+
app publishes itself.
|
|
155
|
+
- Only the app moves on publish and rollback. Functions come back with
|
|
156
|
+
`xflow deploy functions --revision N -m "why"` (`xflow deployments functions` lists the revisions);
|
|
157
|
+
`--project <id>` names the project without a folder.
|
|
158
|
+
- Files of the **three latest successful builds** of each app are kept, plus the live one;
|
|
159
|
+
`xflow deployments` marks the rest `no pages`. The history keeps 30 builds, a revision stays
|
|
160
|
+
while its build is in it or it is among the 10 latest. Keep anything you must not lose in
|
|
161
|
+
your own git repository.
|
|
162
|
+
- Give a person the app address the CLI printed, or the project page it printed. Name builds
|
|
163
|
+
by their number.
|
|
164
|
+
- `xflow status` says how the local copies differ from the server. A deploy rejected before
|
|
165
|
+
the build starts means the server holds a revision this folder has never seen: fetch it next
|
|
166
|
+
to yours (`xflow pull --into ./server-copy`), merge in git, deploy again. `--force` destroys
|
|
167
|
+
that work. A folder with no record of the server revision (a fresh clone, a CI checkout) is
|
|
168
|
+
not rejected: its first deploy goes on top and says so.
|
|
169
|
+
- A deploy that would delete functions gone from the sources refuses until somebody agrees;
|
|
170
|
+
`--allow-removals` is the only way past it without a terminal. Reaching for it to get a
|
|
171
|
+
build running means you deleted something the user never asked you to: put the directories
|
|
172
|
+
back. If the removal is intended, name the functions and let the user answer.
|
|
173
|
+
|
|
174
|
+
## Build gate
|
|
175
|
+
|
|
176
|
+
Before the sandbox starts, the platform checks the sources. Everything below blocks the build,
|
|
177
|
+
all violations come back together with files and lines, and a rejected attempt costs nothing.
|
|
178
|
+
|
|
179
|
+
An app:
|
|
180
|
+
|
|
181
|
+
- `package.json` with the build script named in its `xflow.json` (`npm run build` by default),
|
|
182
|
+
a `vite.config.*` and `vite` in dependencies. No server frameworks: `next`, `nuxt`, Remix,
|
|
183
|
+
`@sveltejs/kit`, `astro`.
|
|
184
|
+
- `index.html` in the app root with `id="root"` and the script that loads `src/main.tsx`
|
|
185
|
+
(`.ts`, `.jsx`, `.js` count too). Code under `src/`; root `app/`, `pages/`, `next/` are rejected.
|
|
186
|
+
- Keep `base` in `vite.config.js` as the template has it: the platform serves each build from
|
|
187
|
+
`/_b/<key>/`, and a build whose `index.html` points elsewhere is refused.
|
|
188
|
+
- The built app at most 15 MB unpacked, the sources at most 10 MB.
|
|
189
|
+
- File names in latin letters, digits, spaces and `. - _ ~` only: `логотип.png` breaks the build.
|
|
190
|
+
- Call functions through `xflow.functions.invoke`, never a hardcoded function address.
|
|
191
|
+
- No keys or tokens in the sources, no server modules (`fs`, `express`, `http`, `child_process`).
|
|
192
|
+
- Outside `src/components/ui` and `src/components/blocks`: no `alert()`, `confirm()`,
|
|
193
|
+
`prompt()` (use Dialog and Toast), no `console.log` (visitors read the console;
|
|
194
|
+
`console.error` and `console.warn` reach the logs).
|
|
195
|
+
- A library that needs a provider (`@tanstack/react-query`, `react-redux`, `sonner`,
|
|
196
|
+
`react-hot-toast`, `react-dnd`) must have it mounted. A missing provider builds fine and
|
|
197
|
+
gives visitors a white screen.
|
|
198
|
+
- The platform files stay byte for byte as they arrived: `src/lib/platform-auth.ts`,
|
|
199
|
+
`src/contexts/platform-auth-context.tsx`, `src/hooks/use-platform-auth.ts`,
|
|
200
|
+
`src/utils/error-logger.ts`, `src/lib/xflow.ts`. The code keeps calling `initPlatformAuth()`
|
|
201
|
+
and `initErrorLogger()` and importing `index.css`, and the Tailwind
|
|
202
|
+
`content` globs keep covering `src/**`. A rejection names the revision to take the original
|
|
203
|
+
from: `xflow pull --revision N --into ./original`, then copy the file back.
|
|
204
|
+
|
|
205
|
+
The project root: function names are lowercase latin letters, digits and hyphens, up to 41
|
|
206
|
+
characters (`send-mail`, not `sendMail`); every name under `functions` in `xflow.json` has its
|
|
207
|
+
`functions/<name>/index.ts`; every caller is an app folder of this project or an existing page
|
|
208
|
+
of the organization (`unknown-caller`).
|
|
209
|
+
|
|
210
|
+
Passes with a line `Unfinished:` instead of blocking: the template's page title, no
|
|
211
|
+
`<link rel="icon">` in `index.html`, an `exports.access` left in a function (it does nothing).
|
|
212
|
+
Fix the first two before you tell the person the app is done.
|
|
213
|
+
|
|
214
|
+
## The template is a starter kit
|
|
215
|
+
|
|
216
|
+
- `src/components/ui` and `src/components/blocks` are a starting set: change them, restyle them
|
|
217
|
+
or delete what you do not use. Any colors, your own color scheme, inline styles, a single
|
|
218
|
+
theme without dark mode: all allowed.
|
|
219
|
+
- The template looks like the xflow interface: warm grays, hairline controls (`ctl-solid`,
|
|
220
|
+
`ctl-raised`, `ctl-inset`, `ctl-select`), segments (`seg-track`, `seg-on`) and surfaces
|
|
221
|
+
(`surface-raised`, `surface-pop`, `surface-modal`) in `src/index.css`.
|
|
222
|
+
- While any template component is left, the theme token names in `:root` of `src/index.css`
|
|
223
|
+
and their `hsl(var(--name))` mapping in the Tailwind config stay: those components paint with
|
|
224
|
+
them. Values change freely; they are HSL components (`216 95% 40%`), not `#hex`. Your own
|
|
225
|
+
colors go under new names.
|
|
226
|
+
- Images and other assets: import them from `src/` (`import logo from './assets/logo.png'`)
|
|
227
|
+
so the build puts them next to the code. An absolute path into `public/` (`/logo.png`) goes
|
|
228
|
+
through the access check of the app and fails inside the xflow frame in Safari.
|
|
229
|
+
|
|
230
|
+
## Who opens an app
|
|
231
|
+
|
|
232
|
+
A person sets this in the web interface; you cannot, and you should not ask for a way around.
|
|
233
|
+
|
|
234
|
+
| Level | Who gets in |
|
|
235
|
+
|---|---|
|
|
236
|
+
| Project members | people who have access to the project |
|
|
237
|
+
| Anyone with the link | anybody, no sign-in at all |
|
|
238
|
+
|
|
239
|
+
- The plan decides which levels exist: on Free an app opens only inside xflow, Start adds the
|
|
240
|
+
direct address and "Anyone with the link".
|
|
241
|
+
- At the closed level the platform signs people in, and a function receives the person in
|
|
242
|
+
`event.xflow.user` (`id`, `role` in the organization, `name`). Keep roles inside the app
|
|
243
|
+
(doctor, receptionist) in your own table keyed by `user.id`.
|
|
244
|
+
- People outside the organization (patients, pickers, clients) are not xflow accounts: make the
|
|
245
|
+
app "Anyone with the link" and give it its own sign-in, see below.
|
|
246
|
+
- At "Anyone with the link" the platform signs nobody in: `event.xflow.user` is null for
|
|
247
|
+
visitors. Accounts, sign-in and who sees which rows are the code of your app, see below.
|
|
248
|
+
- `usePlatformAuth()` in the frontend knows the person only inside the xflow frame, and even
|
|
249
|
+
there it is a hint for drawing the interface, edited from the console by anyone. On the
|
|
250
|
+
direct address it answers `anonymous`. Guard data in the function, by `event.xflow`.
|
|
251
|
+
|
|
252
|
+
## Which functions an app may call
|
|
253
|
+
|
|
254
|
+
The root `xflow.json` names the callers of each function:
|
|
255
|
+
|
|
256
|
+
{
|
|
257
|
+
"projectId": "…",
|
|
258
|
+
"functions": {
|
|
259
|
+
"list-slots": { "callers": ["zapis", "priem"] },
|
|
260
|
+
"book-slot": { "callers": ["zapis", "clinic-landing"] }
|
|
261
|
+
}
|
|
262
|
+
}
|
|
263
|
+
|
|
264
|
+
- A caller is an app folder of this project (`apps/zapis` is `"zapis"`) or the address name of
|
|
265
|
+
a page of the organization (`clinic` for `clinic.xflowpage.ru`). A function without callers is
|
|
266
|
+
left out of `functions` or given `"callers": []`, the same thing.
|
|
267
|
+
- A function nobody lists has no callers: no app and no page reaches it. That is a workflow,
|
|
268
|
+
run by a schedule, a key or `xflow functions invoke`.
|
|
269
|
+
- Callers ship with `xflow deploy functions` and come back with its `--revision N`.
|
|
270
|
+
- The app calls `xflow.functions.invoke('book-slot', { body })` from `src/lib/xflow.ts`. The call
|
|
271
|
+
goes to `/_fn/book-slot` on the app's own address: no function addresses, tokens or keys in
|
|
272
|
+
the bundle, nothing to rebuild when a function changes.
|
|
273
|
+
- A refusal throws `XFlowError` with `status` and `code`: `not_bound` (404, add the caller and
|
|
274
|
+
deploy functions), `not_found` (404, the function is not deployed), `login_required` and
|
|
275
|
+
`invalid_credential` (401, the visitor has to sign in again), `no_access`, `role_too_low`,
|
|
276
|
+
`functions_stopped` (403, minutes ran out or the plan is unpaid: a person settles it),
|
|
277
|
+
`rate_limited` (429), `unavailable` (503, retry later). Branch on `code`, never on the message.
|
|
278
|
+
- A page has to exist before a function can name it: create the page, then deploy functions.
|
|
279
|
+
|
|
280
|
+
## Your function is open to the whole internet
|
|
281
|
+
|
|
282
|
+
A function is open when any of its callers is public: a page (always) or an app at "Anyone
|
|
283
|
+
with the link". `xflow deploy functions` says so in a line of its own, `xflow functions list`
|
|
284
|
+
prints `open`, the web interface marks it.
|
|
285
|
+
|
|
286
|
+
Open means anybody can call it with curl, without your page: the browser is not a gate.
|
|
287
|
+
Hiding the address, checking `Origin` or `Referer`, a token baked into the bundle: all of it is
|
|
288
|
+
readable or forgeable and protects nothing. Write every open function as if the request came
|
|
289
|
+
from a stranger, because it may:
|
|
290
|
+
|
|
291
|
+
- Check every input: types, lengths, allowed values; refuse fields you do not expect. Put input
|
|
292
|
+
into SQL as parameters only (`$1`), never into the text.
|
|
293
|
+
- Return only what this caller needs: no `select *` into a response, no rows of other people,
|
|
294
|
+
no internal fields, no stack traces.
|
|
295
|
+
- Make writes safe to repeat: take a request id from the client and put a unique index on it,
|
|
296
|
+
so a retry or a replay changes nothing.
|
|
297
|
+
- Deduplicate and limit per visitor where it costs: `event.xflow.ip` is the visitor's address,
|
|
298
|
+
set by the platform proxy and not by the caller. The proxy caps requests per address; the
|
|
299
|
+
organization pays for every minute a function runs.
|
|
300
|
+
- A form open to strangers needs a captcha: Cloudflare Turnstile, with the token checked in the
|
|
301
|
+
function against `https://challenges.cloudflare.com/turnstile/v0/siteverify` and the secret
|
|
302
|
+
from `xflow env set`. The site key is public and stays in the source. A check in the browser
|
|
303
|
+
checks nothing.
|
|
304
|
+
- `minRole` on an open function refuses every anonymous visitor (`login_required`): use it only
|
|
305
|
+
where members call.
|
|
306
|
+
|
|
307
|
+
## Sign-in in a public app
|
|
308
|
+
|
|
309
|
+
At the closed levels do none of this: the platform already knows the person.
|
|
310
|
+
|
|
311
|
+
- Passwords: store only a hash, `crypto.scrypt` from Node with a random salt per user, compare
|
|
312
|
+
with `crypto.timingSafeEqual`. Never log a password, never return it, never keep it in the
|
|
313
|
+
browser.
|
|
314
|
+
- Session: after sign-in the function makes a random token (`crypto.randomBytes(32)`), stores
|
|
315
|
+
its SHA-256 and an expiry in a table and returns it as a cookie in its response headers:
|
|
316
|
+
`Set-Cookie: __Host-sid=…; HttpOnly; Secure; SameSite=Lax; Path=/; Max-Age=…`. The `__Host-`
|
|
317
|
+
prefix stops a neighbouring `*.xflowpage.ru` site from planting its own `sid`. `/_fn` is on
|
|
318
|
+
the same address, so the browser sends it back by itself. Not `localStorage`: every script on
|
|
319
|
+
the page reads it.
|
|
320
|
+
- Not the `Authorization` header: `/_fn` replaces it with the platform's own. Nor headers named
|
|
321
|
+
`X-Xflow-*`, `X-Project-Pass`, `X-Server-Key`, `X-Function-Key`: the platform strips them.
|
|
322
|
+
Cookies reach the function as they are.
|
|
323
|
+
- Every function that serves a signed-in visitor reads the cookie from `event.headers`, finds
|
|
324
|
+
the session and filters rows by that user in SQL. A hidden button is not access control.
|
|
325
|
+
- Count failed sign-ins per email and per `event.xflow.ip` in a table and slow them down.
|
|
326
|
+
- Never in the frontend: keys, secrets, the list of users, hashes, a role check that is the only
|
|
327
|
+
guard.
|
|
328
|
+
- The platform sends no email for your app: confirmation and reset letters need a mail provider
|
|
329
|
+
whose key goes into `xflow env set`.
|
|
330
|
+
- `xflow dev` carries neither cookies nor `Set-Cookie`, and calls functions as you (a member).
|
|
331
|
+
Try the sign-in on the app address.
|
|
332
|
+
|
|
333
|
+
## Page or app
|
|
334
|
+
|
|
335
|
+
- A page is finished static files at `https://<name>.xflowpage.ru`: public, live the moment it
|
|
336
|
+
is uploaded, no build, no publish step, no database. A landing page, a presentation, an invoice.
|
|
337
|
+
- An app is source the platform builds: versions and publish, access levels, a database through
|
|
338
|
+
functions. Anything people sign in to, enter data into or come back to.
|
|
339
|
+
- A form open to strangers on a plan without "Anyone with the link" is a page: pages are public
|
|
340
|
+
on every plan.
|
|
341
|
+
- Keep the sources of a page outside the project folder, or list them in `.xflowignore`: the
|
|
342
|
+
root travels with `deploy functions`.
|
|
343
|
+
- A page that needs a backend (a form, a lookup) calls `/_fn/<name>` on its own address with the
|
|
344
|
+
header `X-Xflow-Fn: 1` (without it 403 `bad_request`), and a function of a project answers only
|
|
345
|
+
when its callers name the page. The function is then open. A refusal carries its code in
|
|
346
|
+
`reason` of the JSON body, the same codes as above.
|
|
347
|
+
|
|
348
|
+
## Cloud functions
|
|
349
|
+
|
|
350
|
+
`functions/<name>/index.ts` in the project root exports `handler` (`index.js` and `index.mjs`
|
|
351
|
+
are read too), `export const handler` and `exports.handler` both work. The request arrives as
|
|
352
|
+
`event.httpMethod`, `event.headers`, `event.queryStringParameters` and `event.body`, a string
|
|
353
|
+
(`JSON.parse` it; `event.isBase64Encoded` marks a binary body). The handler returns
|
|
354
|
+
`{ statusCode, body }` where `body` is a JSON string, and may add `headers`.
|
|
355
|
+
`xflow functions list` shows status, callers, `open`, keys, last call and last error.
|
|
356
|
+
|
|
357
|
+
- Dependencies (`pg`, a mail client) go into the root `package.json`; the platform installs them
|
|
358
|
+
on every deploy, and a lock file next to it makes that exact.
|
|
359
|
+
- Code shared by functions lives in a root folder such as `lib/`, imported by relative path: each
|
|
360
|
+
function is bundled with what it imports. A folder in `functions/` without `index.*` is not a
|
|
361
|
+
function. Read `process.env` in `functions/<name>/` itself: `xflow env check` looks only there.
|
|
362
|
+
|
|
363
|
+
Keep one shape inside that string across the project: `{ success: true, data }` when it worked,
|
|
364
|
+
`{ success: false, error: { message, code } }` when it did not. Branch the frontend on
|
|
365
|
+
`error.code`, never on `error.message`.
|
|
366
|
+
|
|
367
|
+
A function whose code and variables did not change is not shipped again, and one that fails to
|
|
368
|
+
ship fails the whole deploy.
|
|
369
|
+
|
|
370
|
+
Debugging a deployed function is two commands: `xflow functions invoke <name>` calls it as you,
|
|
371
|
+
through the platform, and prints status, timing and body (`--data '{"a":1}'`, `--data-file
|
|
372
|
+
body.json`, `--method GET`, `--json` for the body alone); `xflow functions logs <name>` shows
|
|
373
|
+
the crashes and 5xx answers with stacks and console output, the latest 10 (`--limit N` for more).
|
|
374
|
+
Only failed calls are logged. Empty output does not clear a function that fails at module start,
|
|
375
|
+
runs over its time cap or out of memory: those never reach the logs, `invoke` shows them.
|
|
376
|
+
|
|
377
|
+
The body has to be JSON and the CLI checks it before calling. In PowerShell the double quotes
|
|
378
|
+
never reach the CLI (`--data '{"a":1}'` arrives as `{a:1}`): escape them (`--data '{\"a\":1}'`)
|
|
379
|
+
or pass a file. It bites `--payload` of a schedule the same way. A command that worked writes
|
|
380
|
+
nothing to stderr, so a red line there means it really failed.
|
|
381
|
+
|
|
382
|
+
### Who is calling
|
|
383
|
+
|
|
384
|
+
The platform checks every call before your code runs and hands the answer over in `event.xflow`:
|
|
385
|
+
|
|
386
|
+
```js
|
|
387
|
+
exports.handler = async (event) => {
|
|
388
|
+
const { caller, slug, user, ip } = event.xflow
|
|
389
|
+
// caller: 'app' (an app of this project), 'page', 'service' (another function of this
|
|
390
|
+
// project), 'external' (an outside service with a key), 'schedule',
|
|
391
|
+
// 'platform' (a person through xflow functions invoke or the web interface)
|
|
392
|
+
// slug: the address name of the calling app (<id>--<org>) or page, null otherwise
|
|
393
|
+
// user: { id, role, name } of a signed-in person,
|
|
394
|
+
// null for anonymous visitors, pages, keys
|
|
395
|
+
// ip: the visitor's address, null for a schedule
|
|
396
|
+
}
|
|
397
|
+
```
|
|
398
|
+
|
|
399
|
+
Never trust an identity that arrives in the body or in a header of the request: the page lives
|
|
400
|
+
on someone else's computer. `event.xflow` is the only identity the platform stands behind.
|
|
401
|
+
|
|
402
|
+
A function that changes data should say who may call it instead of checking the role by hand:
|
|
403
|
+
|
|
404
|
+
```js
|
|
405
|
+
exports.minRole = 'developer' // 'member' | 'developer' | 'owner'
|
|
406
|
+
```
|
|
407
|
+
|
|
408
|
+
The platform refuses anything below that role before your code runs; it applies to people
|
|
409
|
+
(apps, pages, `functions invoke`), not to keys and schedules. `member` is the people who only
|
|
410
|
+
use the apps (clinic employees, managers), `developer` and `owner` build them. In the web
|
|
411
|
+
interface these roles are called «Просмотр» (`member`), «Редактор» (`developer`) and «Админ»
|
|
412
|
+
(`owner`). Without the line
|
|
413
|
+
every member of the project can call the function. Losing access
|
|
414
|
+
closes the function within a minute.
|
|
415
|
+
|
|
416
|
+
- Another function of the project: `fetch(`${process.env.XFLOW_FN_URL}/<name>`, { headers:
|
|
417
|
+
{ 'X-Server-Key': process.env.XFLOW_SERVER_KEY } })`. The key opens the functions of its own
|
|
418
|
+
project only, whatever their callers.
|
|
419
|
+
- An outside service (a payment webhook, a bot, a CRM) calls
|
|
420
|
+
`https://fn.xflowpage.ru/<projectId>/<name>` (`xflow functions list` prints it) with a key of
|
|
421
|
+
that function in `X-Function-Key` or `?key=`. Keys are issued by a person on the function's
|
|
422
|
+
screen in the web interface, never by you: ask the user. A function holds at most two keys,
|
|
423
|
+
the second one to replace the first without downtime.
|
|
424
|
+
- `exports.access` does nothing any more: who may call is `callers`.
|
|
425
|
+
|
|
426
|
+
## Secrets and connected accounts
|
|
427
|
+
|
|
428
|
+
Keys and passwords live on the platform, not in the repository: `xflow env set SMTP_PASSWORD=…`
|
|
429
|
+
writes one, `xflow env` lists the names, `xflow env check` names the variables your functions
|
|
430
|
+
read but the platform does not have. Values never come back out: the only place they exist is
|
|
431
|
+
inside the running function. Apps get no variables at all.
|
|
432
|
+
|
|
433
|
+
A variable goes to the whole organization unless you say otherwise: `--scope project` keeps it
|
|
434
|
+
to this project alone, `--scope organization` is the default, and a third word is refused.
|
|
435
|
+
Pick the narrow one for anything that belongs to one project. These commands see only what
|
|
436
|
+
this project can see, so `env rm` reports a variable of another project missing even though
|
|
437
|
+
names are unique within the organization.
|
|
438
|
+
|
|
439
|
+
`DATABASE_URL` and every name starting with `XFLOW` are filled in by the platform: writing them
|
|
440
|
+
is refused.
|
|
441
|
+
|
|
442
|
+
Some variables come from a connected account instead of from you. Credentials of an account
|
|
443
|
+
linked to the project show up in `xflow env` marked read-only, under a prefix chosen at link
|
|
444
|
+
time (`YANDEX_DIRECT_TOKEN`, `YANDEX_DIRECT_CLIENT_LOGIN`): read them like any other variable.
|
|
445
|
+
If calls to that service start failing on authorisation, `xflow status` says whether the token
|
|
446
|
+
is merely expiring (any deploy of the functions renews it) or the account was disconnected on
|
|
447
|
+
the provider's side, which only a human can reconnect.
|
|
448
|
+
|
|
449
|
+
`xflow connections` lists those accounts: the ones linked to this project, with the alias and
|
|
450
|
+
the state of the access, and the ones the organization has but this project does not use yet,
|
|
451
|
+
marked `available, not linked`. Check it before telling anyone a service is unavailable.
|
|
452
|
+
|
|
453
|
+
`xflow connections link "Яндекс Метрика" --as YANDEX_METRIKA` is that link and
|
|
454
|
+
`xflow connections unlink YANDEX_METRIKA` undoes it; `xflow help connections` has the naming
|
|
455
|
+
rules. In the project folder unlink refuses while a function still reads one of the variables,
|
|
456
|
+
naming those functions, so read that list before reaching for `--force`.
|
|
457
|
+
|
|
458
|
+
Linking needs the `connections:link` right on the key, and only accounts granted to the owner
|
|
459
|
+
of the key personally can be linked at all. A key cannot grant it to itself: ask the person.
|
|
460
|
+
Connecting a new account and switching one off stay with a person too.
|
|
461
|
+
|
|
462
|
+
### Asking an API what it returns
|
|
463
|
+
|
|
464
|
+
```
|
|
465
|
+
xflow connections call WB /api/v1/supplier/stocks?dateFrom=2026-09-01
|
|
466
|
+
xflow connections call "Яндекс Метрика" /management/v1/counters
|
|
467
|
+
xflow connections call OZON /v1/product/list --method POST --data '{}' \
|
|
468
|
+
--header '{"Client-Id":"{CLIENT_ID}"}'
|
|
469
|
+
```
|
|
470
|
+
|
|
471
|
+
The platform attaches the credentials and makes the request itself: no deploy, and the key never
|
|
472
|
+
reaches you. A linked account is called by its alias, an `available, not linked` one by its
|
|
473
|
+
name: linking first is not needed to look. Calling is looking, not wiring: to use the account
|
|
474
|
+
in code, link it and deploy functions.
|
|
475
|
+
|
|
476
|
+
`{NAME}` in the path or in a header value is filled in from the fields of the connection. Take
|
|
477
|
+
the names from `xflow connections`, which prints them in braces: an invented name is left in the
|
|
478
|
+
text and the request goes out anyway, into somebody's live account. Ask for the shape, not the
|
|
479
|
+
volume: one day and `limit=1`; `--json | jq '.response.body | keys'` gives the field names
|
|
480
|
+
without the body entering your context. `POST` and `DELETE` change things in a live account and
|
|
481
|
+
nothing undoes that: ask the person first when the endpoint is not clearly a read.
|
|
482
|
+
|
|
483
|
+
## Schedules
|
|
484
|
+
|
|
485
|
+
`xflow schedules set report "0 3 ? * * *"` runs a function daily at 03:00. Six fields, UTC,
|
|
486
|
+
and exactly one of day-of-month / day-of-week must be `?`. A run reaches the handler as a POST
|
|
487
|
+
with `event.xflow.caller === 'schedule'`, and `--payload '{"mode":"full"}'` (or
|
|
488
|
+
`--payload-file body.json`) is its body. The function has to be deployed first.
|
|
489
|
+
|
|
490
|
+
```
|
|
491
|
+
xflow env set SMTP_PASSWORD=... # secrets first: values ride the next deploy
|
|
492
|
+
# write functions/report/index.ts, reading process.env.SMTP_PASSWORD literally
|
|
493
|
+
xflow deploy functions -m "Nightly report"
|
|
494
|
+
xflow schedules set report "0 3 ? * * *" --payload '{"mode":"full"}'
|
|
495
|
+
xflow functions invoke report # run it once
|
|
496
|
+
xflow functions logs report # crashes of real runs
|
|
497
|
+
```
|
|
498
|
+
|
|
499
|
+
## Database
|
|
500
|
+
|
|
501
|
+
Schema changes are files: `migrations/0001_init.sql`, `migrations/0002_orders.sql` in the
|
|
502
|
+
project root, applied in filename order by `xflow db migrate` from any folder of the project.
|
|
503
|
+
`xflow db status` shows what is applied and what waits. Never edit an applied file, write a new
|
|
504
|
+
migration instead. Every project has exactly one database of its own, shared by all its apps and
|
|
505
|
+
functions.
|
|
506
|
+
|
|
507
|
+
The browser never reaches the database directly. The app reads and writes through a cloud
|
|
508
|
+
function, and inside the handler the connection string is already there:
|
|
509
|
+
|
|
510
|
+
```js
|
|
511
|
+
const { Client } = require('pg')
|
|
512
|
+
const db = new Client({ connectionString: process.env.DATABASE_URL })
|
|
513
|
+
```
|
|
514
|
+
|
|
515
|
+
The platform passes `DATABASE_URL` only to functions that mention it and sets the project schema
|
|
516
|
+
on every connection, so plain table names (`select * from tasks`) hit your project.
|
|
517
|
+
|
|
518
|
+
`migrations/` says what you did; `xflow db schema [table]` says what is in the database now, and
|
|
519
|
+
`xflow db query 'select ...'` reads it inside a READ ONLY transaction (50 rows by default,
|
|
520
|
+
`--limit` up to 300; `--json` prints long values whole). Single quotes hold in PowerShell, bash
|
|
521
|
+
and zsh, cmd.exe wants double ones; a query with quotes of its own goes in a `.sql` file outside
|
|
522
|
+
the project, `xflow db query ../q.sql`.
|
|
523
|
+
|
|
524
|
+
The platform keeps no database history and no backups, so anything that destroys data
|
|
525
|
+
(`DROP TABLE`, `DROP COLUMN`, `TRUNCATE`, `DELETE`) needs both the `--allow-destructive` flag and
|
|
526
|
+
the right to destroy data on the key, which is off by default and only its owner turns on. It is
|
|
527
|
+
judged by the result, not the text: a migration that dropped or emptied a table, dropped a column
|
|
528
|
+
or deleted rows is rolled back, however the SQL was written. `BEGIN`/`COMMIT` in a migration are
|
|
529
|
+
refused: each one already runs in its own transaction. When the refusal is about the right, the flag changes nothing: say what
|
|
530
|
+
needs deleting and why, and let the person decide. With both in place the affected tables are
|
|
531
|
+
dumped first (up to 50 000 rows each) and kept for 7 days; getting a dump back is a request to
|
|
532
|
+
the person, no command does it. Check with `--dry-run`.
|
|
533
|
+
|
|
534
|
+
An organization can have own database servers. `xflow db list` names the server of each project
|
|
535
|
+
database (`platform` is the common one) and the own servers with the room used.
|
|
536
|
+
- A new project with its database on a chosen server: `xflow init --server <name>`.
|
|
537
|
+
- An existing one: `xflow db move --to <name> --confirm <project name>`. Writes close while it
|
|
538
|
+
copies, usually a couple of minutes; the platform switches the functions itself. It needs the
|
|
539
|
+
right to move databases, off on the key by default: refused for the right, say what should move
|
|
540
|
+
where and why, and the person turns it on or moves it in the «Базы данных» (Databases) section.
|
|
541
|
+
- Buying, paying for and deleting servers are the person's, in the web interface.
|
|
542
|
+
|
|
543
|
+
Code stays the same on an own server: pass `DATABASE_URL` as is, without an `ssl` option. While
|
|
544
|
+
an own server is not running, migrations and queries say so and functions that use the database
|
|
545
|
+
time out: tell the person instead of retrying.
|
|
546
|
+
|
|
547
|
+
An own server comes tuned and guarded, so do not tune it from migrations:
|
|
548
|
+
- Installed: `pgcrypto`, `pg_trgm`, `unaccent`, `citext`, `btree_gin`, `btree_gist`,
|
|
549
|
+
`pg_stat_statements`. `gen_random_uuid()` is built in everywhere, `uuidv7()` on an own server.
|
|
550
|
+
Never `uuid-ossp`. Anything else (`postgis`, `pgvector`) is a request to the person.
|
|
551
|
+
- A statement is cut after 30 seconds, waiting for a lock after 3, a transaction left open after
|
|
552
|
+
30. A query that needs longer is a wrong query (a missing index, or a report that belongs in a
|
|
553
|
+
scheduled function writing a summary table). A scheduled job that genuinely needs more runs
|
|
554
|
+
`SET statement_timeout = '5min'` on its own connection. A database that used `citext` or
|
|
555
|
+
another extension type cannot move back to `platform`.
|
|
556
|
+
- A restart on a plan change takes about a minute. Create the `Client` inside the handler, or
|
|
557
|
+
keep a `Pool` at module level: a `Client` created at module level dies with the restart.
|
|
558
|
+
|
|
559
|
+
## File storage
|
|
560
|
+
|
|
561
|
+
**Static assets of an app** (product photos, video, PDFs, big artwork) you upload yourself:
|
|
562
|
+
|
|
563
|
+
```bash
|
|
564
|
+
xflow storage push ./media --to media # a folder, its structure kept
|
|
565
|
+
xflow storage ls # what is there, with addresses and sizes
|
|
566
|
+
```
|
|
567
|
+
|
|
568
|
+
`push` prints the address of every file (`/_files/<id>`) and skips what is already stored under
|
|
569
|
+
the same path and size; `--replace` overwrites a file whose size differs and keeps its address.
|
|
570
|
+
Use the address as is inside an app: the app's own host serves it to whoever may open the app,
|
|
571
|
+
including anonymous visitors of a public one. Icons, fonts and small artwork stay in the
|
|
572
|
+
repository.
|
|
573
|
+
|
|
574
|
+
Deleting needs a right of its own, off by default, so `xflow storage rm` may answer that the key
|
|
575
|
+
was not granted it. Ask the person and do not look for a way around: whatever the users of the
|
|
576
|
+
app uploaded lives in the same folders, and there is no undo. A folder is
|
|
577
|
+
`xflow storage rm --folder <path> --yes`.
|
|
578
|
+
|
|
579
|
+
**Files that users of the app upload** go through a cloud function of your own: it asks the
|
|
580
|
+
platform for a one-time link, the browser sends the bytes straight to storage, and a second call
|
|
581
|
+
records the file:
|
|
582
|
+
|
|
583
|
+
```js
|
|
584
|
+
const link = await fetch(`${process.env.XFLOW_API_URL}/api/storage/project/upload-url`, {
|
|
585
|
+
method: 'POST',
|
|
586
|
+
headers: {
|
|
587
|
+
'Content-Type': 'application/json',
|
|
588
|
+
'X-Server-Key': process.env.XFLOW_SERVER_KEY,
|
|
589
|
+
},
|
|
590
|
+
body: JSON.stringify({ fileName, fileSize, contentType, folderPath: 'invoices' }),
|
|
591
|
+
}).then((r) => r.json())
|
|
592
|
+
```
|
|
593
|
+
|
|
594
|
+
`confirm` takes the returned `s3Key` and answers with the file and its address; `delete` takes
|
|
595
|
+
that same `url`. No endpoint lists files back, so write the address into a table of your own in
|
|
596
|
+
the same call. What a visitor may do with files is decided inside that function; never send the
|
|
597
|
+
key to the frontend.
|
|
598
|
+
|
|
599
|
+
- A name already taken in that folder is refused before the link is issued; `overwrite: true`
|
|
600
|
+
replaces the bytes and keeps the address.
|
|
601
|
+
- 200 MB per file and the storage quota of the organization, checked again on `confirm`.
|
|
602
|
+
- Confirm only after the PUT has finished, and send on the PUT exactly the `Content-Type` you
|
|
603
|
+
named: the link is signed for it, a different or missing type gets 403.
|
|
604
|
+
- Assets only: pages, scripts and executables (`html`, `js`, `exe`, …) are refused with
|
|
605
|
+
`forbidden_type`.
|
|
606
|
+
|
|
607
|
+
A refusal comes back as `{ error, code }` (`invalid_name`, `file_too_large`, `quota_exceeded`,
|
|
608
|
+
`not_uploaded`, `duplicate_name`, `forbidden_type`, `not_found`, …): branch on `code`.
|
|
609
|
+
|
|
610
|
+
## Pages
|
|
611
|
+
|
|
612
|
+
A page is a public static site at `https://<name>.xflowpage.ru`, outside projects. Anyone with
|
|
613
|
+
the address opens it, without signing in.
|
|
614
|
+
|
|
615
|
+
- `xflow pages create "Price list" ./dist` makes a page with the built site on it and prints its
|
|
616
|
+
address: there are no empty pages. `--slug price-list` picks the name, otherwise it comes from
|
|
617
|
+
the title with a random tail.
|
|
618
|
+
- `xflow pages deploy <page> <folder|.zip|.html> -m "what changed"` uploads a new version.
|
|
619
|
+
- **Both are public the moment the command finishes**: no draft, no publish step.
|
|
620
|
+
- `xflow pages status <page>` lists the versions, `xflow pages rollback <page> <N>` puts one back
|
|
621
|
+
in seconds; the files of the last 5 are kept.
|
|
622
|
+
- `xflow pages rm <page> --yes` deletes the page: the address goes empty and every version is
|
|
623
|
+
gone for good, without `--yes` the command names what goes and stops. The name stays reserved
|
|
624
|
+
for the organization. A page put up to try something out is yours to take down when you are
|
|
625
|
+
done: do not leave it standing.
|
|
626
|
+
- Names are 3-40 characters. At most 100 pages per organization, 20 new and 200 uploads a day,
|
|
627
|
+
10 seconds between uploads of one page: batch changes into one upload.
|
|
628
|
+
- Static files only, what the build writes (`dist`), never a folder with `package.json`. At most
|
|
629
|
+
5 MB zipped, 25 MB unpacked, 1000 files. Everything a page shows travels inside it: project
|
|
630
|
+
file storage does not serve pages.
|
|
631
|
+
- A backend for a page: see **Page or app**.
|
|
632
|
+
- Everything in a page is readable by every visitor. A known key format gets the upload refused,
|
|
633
|
+
anything else simply leaks.
|
|
634
|
+
- Search engines are asked not to index pages or apps: do not promise SEO.
|
|
635
|
+
- The tab icon is the platform's on every page: do not spend a request on a favicon of your own.
|
|
636
|
+
- The MCP `pages` tool uploads one self-contained HTML document up to 150 KB.
|
|
637
|
+
- A page is deleted by whoever made it, or by the owner of the organization. Switching a page
|
|
638
|
+
off for a while is for a person, in the platform interface.
|
|
639
|
+
|
|
640
|
+
## Organizations and keys
|
|
641
|
+
|
|
642
|
+
One key per organization, stored side by side: `xflow org` lists them, `xflow org switch
|
|
643
|
+
<name|id>` changes the active one, `xflow help org` has the precedence rules.
|
|
644
|
+
|
|
645
|
+
Inside a project folder commands follow the organization the folder is bound to, whatever the
|
|
646
|
+
active one is. `--project <id>` and `--app <id>` ignore the folder whole (`xflow help project`
|
|
647
|
+
lists the commands that take them). A "not found" on a project you know exists usually means the
|
|
648
|
+
key belongs to another organization: check `xflow org`; signing in to a missing organization is
|
|
649
|
+
`xflow login`, and that needs a person with a browser.
|
|
650
|
+
|
|
651
|
+
A key has its owner's level in each project. With view-only access reading works (`projects
|
|
652
|
+
get`, logs, `db query`, `pull`), and every change fails with `Your access to this project is
|
|
653
|
+
view-only`. That is not a bug to work around: tell the person, edit access is theirs to ask for.
|
|
654
|
+
|
|
655
|
+
## Direct access without the terminal
|
|
656
|
+
|
|
657
|
+
The platform also exposes an MCP server, connected with `xflow mcp install`. When its tools are
|
|
658
|
+
available, prefer them for control-plane work: project state, database schema and read-only
|
|
659
|
+
queries, migrations, function logs and invocations, schedules, variables, app builds and
|
|
660
|
+
publish. They say explicitly when a result is truncated.
|
|
661
|
+
|
|
662
|
+
Anything that depends on the working copy stays in the CLI: sending sources, building apps and
|
|
663
|
+
deploying functions (`xflow deploy`), creating projects and apps (`xflow init`,
|
|
664
|
+
`xflow apps add`). The tools cannot see your folder. Access levels, function keys, money and
|
|
665
|
+
people are set by a person in the web interface.
|
|
666
|
+
|
|
667
|
+
## Do not
|
|
668
|
+
|
|
669
|
+
- Deploy with `--force` without checking `xflow status` first.
|
|
670
|
+
- Invent platform commands: what is not in `xflow help` does not exist.
|
|
671
|
+
- Ask for a way to change an app's access level or issue a function key: that is the person's.
|
|
672
|
+
|
|
673
|
+
## App design
|
|
674
|
+
|
|
675
|
+
- Take a block from `src/components/blocks` or a primitive from `src/components/ui` before
|
|
676
|
+
writing your own layout; replace or delete them when the design needs something else.
|
|
677
|
+
- Dropdowns, checkboxes, radios and dates through `Select`, `Checkbox`, `RadioGroup`,
|
|
678
|
+
`DatePicker` from `src/components/ui`: a bare `<select>` opens the system list in Safari
|
|
679
|
+
and Firefox, out of the app's style.
|
|
680
|
+
- Every screen starts with a clear header; header, filters and content in one column.
|
|
681
|
+
- Draw all four states: loading, error, empty, data. An empty screen says what appears here and
|
|
682
|
+
offers an action.
|
|
683
|
+
- Colour only when it communicates: status, action, error, success. Grey carries the structure.
|
|
684
|
+
- Density over air: people scan and compare. Numbers in a column, `tabular-nums`.
|
|
685
|
+
- Name the shape first: list, list with detail, dashboard, form, board.
|
|
686
|
+
- Seed 5-10 believable rows in the first migration: a screen with zero rows looks unfinished.
|
|
687
|
+
- Give the app its own page title and icon.
|
|
688
|
+
|
|
689
|
+
## Errors from a deployed app
|
|
690
|
+
|
|
691
|
+
`xflow logs` prints what broke in the browser on the app addresses: unhandled errors, rejected
|
|
692
|
+
promises and 5xx responses; in an app folder that app, in the project root every app.
|
|
693
|
+
`xflow functions logs` prints function crashes. A person sees the same in the web interface:
|
|
694
|
+
browser errors in the «Ошибки» (Errors) panel of the app, function crashes on the «Ошибки» tab
|
|
695
|
+
of the function's screen. The last 200 records of each stream are kept.
|
|
696
|
+
|
|
697
|
+
Run an app locally with `xflow dev` in its folder, not a bare `npm run dev`: every `/_fn/<name>`
|
|
698
|
+
call then goes to the platform as this app, with the same callers and access as on its address,
|
|
699
|
+
and a function someone else deployed answers at once. A bare `npm run dev` has no key, so its
|
|
700
|
+
function calls fail. The server answers `127.0.0.1` alone, because it holds that key. A local
|
|
701
|
+
run reports nothing to the logs.
|
|
702
|
+
|
|
703
|
+
## Environment
|
|
704
|
+
|
|
705
|
+
For CI and agent runs: `XFLOW_TOKEN` replaces `xflow login`, `XFLOW_API_URL` points at another
|
|
706
|
+
platform host. There is no `.env` from the platform: the bundle carries no tokens or addresses.
|