@getxflow/cli 0.3.1 → 0.3.3

package/dist/commands/functions.js

@@ -8,6 +8,12 @@ const config_1 = require("../config");
 const errors_1 = require("../errors");
 const session_1 = require("../session");
 const ui_1 = require("../ui");
+/** Who can call the function: inside the app only, or an outside service holding a key. */
+function accessLabel(fn) {
+    if (!fn.external_keys)
+        return 'in-app only';
+    return `external (${fn.external_keys} key${fn.external_keys > 1 ? 's' : ''})`;
+}
 const FUNCTIONS_DIR = 'functions';
 async function functionsList() {
     const { config } = (0, config_1.requireProject)();
@@ -20,6 +26,7 @@ async function functionsList() {
     (0, ui_1.table)(data.functions.map((fn) => [
         fn.name,
         fn.status === 'deployed' ? 'deployed' : fn.status === 'failed' ? 'failed' : fn.status,
+        accessLabel(fn),
         fn.last_deployed_at ? (0, ui_1.formatAge)(fn.last_deployed_at) : '-',
         fn.error_message ?? '',
     ]));

package/dist/version.js

@@ -2,6 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_API_URL = exports.CLI_VERSION = void 0;
 /** Keep in sync with cli/package.json. */
-exports.CLI_VERSION = '0.3.1';
+exports.CLI_VERSION = '0.3.3';
 /** Overridden by XFLOW_API_URL or the `api` field in xflow.json. */
 exports.DEFAULT_API_URL = 'https://app.getxflow.com';

package/package.json

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

package/skills/xflow/SKILL.md

@@ -6,8 +6,9 @@ description: Build, deploy and publish apps on the XFlow platform with the xflow
 # XFlow
 
 Hosting for web apps. The code lives in an ordinary repository on the developer
-machine and is built locally; the platform takes the finished build and serves it.
-A platform project is recognized by the `xflow.json` file in its root.
+machine, `xflow deploy` sends the sources, and the platform builds them in a clean
+sandbox and serves the result as static files. A platform project is recognized by
+the `xflow.json` file in its root.
 
 ## First rule
 
@@ -134,6 +135,12 @@ separate deploy command: `xflow deploy` ships the functions and then builds the
 in that order. List what is live with `xflow functions list`. The handler returns
 `{ statusCode, body }` where `body` is a JSON string.
 
+Keep one shape inside that string across the whole project: `{ success: true, data }`
+when it worked, `{ success: false, error: { message, code } }` when it did not. Nothing
+enforces this, but a project where every function answers its own way costs an adapter
+on every call. Branch the frontend on `error.code`, never on `error.message`: wording
+gets rewritten on any edit, a code does not.
+
 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
@@ -180,20 +187,27 @@ exports.minRole = 'admin'   // 'member' | 'developer' | 'admin' | 'owner'
 The wrapper refuses anything below that role before your code runs. Without the line every
 member of the project can call the function, including the ones who may only look at apps.
 
-Losing access closes the function within a minute, so a removed member cannot keep calling it.
+Losing access closes the function within five minutes, so a removed member cannot keep calling it.
 Opening the deployed address directly does not work either: there is no pass outside the
 platform.
 
-Calling a function from another function is a server call and uses the server key of the
-project: send `process.env.XFLOW_SERVER_KEY` in the `X-Server-Key` header.
+Calling a function from another function is a server call. Send two headers, both from the
+environment the platform fills in: `X-Project-Token` with `process.env.XFLOW_PROJECT_TOKEN`
+and `X-Server-Key` with `process.env.XFLOW_SERVER_KEY`. The token is the ticket into the
+project and the key is the identity; the wrapper checks the ticket first, so the key alone
+answers 401.
 
 An outside service (a webhook from a payment provider, a bot, a CRM) has no person behind it
 and needs a key of that one function. Keys are not issued by default and the CLI cannot
-create one: a human opens the function in the web interface, section "Внешний доступ", and
-issues it there. Ask the user to do that and to paste the address back to you — never invent
+create one: a human issues it in the project settings: «Облачные функции» → the function →
+«Настройки». Ask the user to do that and to paste the address back to you — never invent
 another way in. A function holds at most two keys, and the second one exists to replace the
 first without downtime, not to serve a second consumer.
 
+`xflow functions list` shows who can reach each function: `in-app only` (no keys, answers
+only inside the application) or `external (N keys)` (a human issued external access). Key
+values are never shown there.
+
 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
@@ -259,8 +273,34 @@ const link = await fetch(`${process.env.XFLOW_API_URL}/api/storage/project/uploa
 }).then((r) => r.json())
 ```
 
-`confirm` takes the same fields plus the returned `s3Key` and makes the file visible to the
-app; `delete` takes the file `url`. Never pipe the bytes through the function itself.
+`confirm` takes the same fields plus the returned `s3Key` and answers with the file and its
+public address; `delete` takes the file `url`. Never pipe the bytes through the function itself.
+
+There is no endpoint that lists the files back, so the address that `confirm` returns is the
+only copy you get: write it into a table of your own in the same call, and the application
+reads its files from there.
+
+Four things bite an upload that otherwise looks right, and none of them is obvious from the
+answers you get:
+
+- **The content type can quietly split in two.** Nothing checks that the `Content-Type` the
+  browser sends on the PUT matches the one you named in `upload-url`: both calls answer 200.
+  But storage keeps the header the browser sent and serves the file under it, while the
+  record keeps the one you named, so a card can say `image/png` about a file every browser
+  treats as HTML. Send the same string in both calls and they cannot drift.
+- **The same name in the same folder is refused.** Names are unique per folder, so a second
+  `avatar.png` fails instead of replacing the first. Give the name a suffix of your own, or
+  delete the old file before confirming the new one.
+- **The limits are 200 MB per file and the storage quota of the organization.** The quota is
+  checked again on `confirm`, by the real size, which means a refusal can land after the
+  bytes are already up; the platform then removes the object and your table stays clean.
+- **Confirm only after the PUT has finished.** The platform looks the object up in storage
+  and takes its real size from there, not from what you declared, so an early `confirm`
+  answers that the file is not there.
+
+A refusal comes back as `{ error, code }`. Branch on `code` (`invalid_name`, `file_too_large`,
+`quota_exceeded`, `not_uploaded`, `duplicate_name`, `not_found`, …) and never on the text:
+the wording is free to change, the code is not.
 
 What the app may do with files is decided inside that function, because the page in the
 browser can be edited by whoever opened it. Never write the key into the sources and never