@getxflow/cli 0.2.0 → 0.3.1

package/dist/bin.js

@@ -69,10 +69,6 @@ async function run(args) {
             }
             throw new errors_1.CliError(`Unknown command: mcp ${second}`, 'Available: install');
         case 'functions':
-            // The command is gone, but silence would leave the habit unexplained.
-            if (second === 'deploy') {
-                throw new errors_1.CliError('Functions are deployed by the build now', 'Run xflow deploy: it ships the functions and then builds the application with their addresses');
-            }
             if (second === 'invoke') {
                 await (0, functions_1.functionsInvoke)(rest);
                 return;

package/dist/commands/functions.js

@@ -49,6 +49,17 @@ async function functionsInvoke(args) {
     const data = (0, args_1.flagString)(args, 'data');
     const method = ((0, args_1.flagString)(args, 'method') ?? (data ? 'POST' : 'GET')).toUpperCase();
     const sendsBody = method !== 'GET' && method !== 'HEAD';
+    // A pass for the person who owns the key: the project token alone is not an
+    // identity, and a project built with the current template refuses without one.
+    // A read-only key cannot get a pass, so the call still goes out without it.
+    let pass = '';
+    try {
+        const issued = await (0, api_1.apiJson)(client, `/api/v1/projects/${config.projectId}/pass`, { method: 'POST' });
+        pass = issued.pass;
+    }
+    catch {
+        (0, ui_1.note)((0, ui_1.dim)('  Could not get a visitor pass: calling with the project token only'));
+    }
     const started = Date.now();
     let response;
     try {
@@ -57,6 +68,7 @@ async function functionsInvoke(args) {
             headers: {
                 'Content-Type': 'application/json',
                 'X-Project-Token': card.project_token ?? '',
+                ...(pass ? { 'X-Project-Pass': pass } : {}),
             },
             body: sendsBody ? (data ?? '{}') : undefined,
             // Wait past the function's own 90 s cap to see its timeout, not ours.

package/dist/commands/projects.js

@@ -63,7 +63,7 @@ async function init(args) {
     }
     (0, ui_1.step)('Fetching the template');
     const archive = await (0, api_1.apiBinary)(client, `/api/v1/templates/${templateId}/archive`);
-    const files = (0, zip_1.zipRead)(archive);
+    const files = (0, zip_1.dropDirectoryEntries)((0, zip_1.zipRead)(archive));
     (0, ui_1.step)('Creating the project on the platform');
     const project = await (0, api_1.apiJson)(client, '/api/v1/projects', {
         method: 'POST',

package/dist/commands/sources.js

@@ -47,7 +47,7 @@ async function confirmForce(client, projectId, server, local) {
     (0, ui_1.warn)(`The server holds revision ${server.revision} from ${(0, ui_1.formatAge)(server.created_at)}, ${server.file_count} files`);
     try {
         const info = await (0, api_1.apiJson)(client, `/api/v1/projects/${projectId}/pull`);
-        const serverPaths = new Set((0, zip_1.zipRead)(await (0, api_1.downloadUrl)(info.download_url)).map((e) => e.path));
+        const serverPaths = new Set((0, zip_1.dropDirectoryEntries)((0, zip_1.zipRead)(await (0, api_1.downloadUrl)(info.download_url))).map((e) => e.path));
         const localPaths = new Set(local.map((f) => f.path));
         const disappearing = [...serverPaths].filter((p) => !localPaths.has(p));
         if (disappearing.length > 0) {
@@ -132,7 +132,7 @@ async function pull(args) {
         (0, ui_1.warn)('The hash of the downloaded tree did not match the server one: the contents may have changed in transit');
     }
     (0, node_fs_1.mkdirSync)(target, { recursive: true });
-    for (const entry of entries) {
+    for (const entry of (0, zip_1.dropDirectoryEntries)(entries)) {
         const path = (0, node_path_1.join)(target, entry.path);
         (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
         (0, node_fs_1.writeFileSync)(path, entry.content);

package/dist/help.js

@@ -150,8 +150,9 @@ A failed run shows up in ${(0, ui_1.bold)('xflow functions logs')}: nobody is wa
 function, so the wrapper reports a crash the same way it does on an ordinary call.`,
     invoke: `${(0, ui_1.bold)('xflow functions invoke')} <name>: call a function
 
-Calls it exactly the way the application does, with the X-Project-Token header. The
-token is taken from the project card on the platform, no local .env is needed.
+Calls it exactly the way the application does: the project token plus a visitor pass
+for the person who owns the key, so the function sees a real caller and its role.
+Both are taken from the platform, no local .env is needed.
 
   --data '{"a":1}'   request body (the method becomes POST by default)
   --method GET       a different method

package/dist/template.js

@@ -25,7 +25,7 @@ xflow publish     # show the dev version to visitors
 \`\`\`
 
 The interface is built on the template components: \`src/components/ui\` (buttons, fields,
-dialogs) and \`src/components/blocks\` (table, form, filters, kanban, charts). Layout built
+dialogs) and \`src/components/blocks\` (a data table and charts). Layout built
 on top of them looks like the rest of the platform, while custom colors in place of the
 tokens from \`src/index.css\` break that consistency.
 

package/dist/tree.js

@@ -19,6 +19,9 @@ const DEFAULT_IGNORE = [
     '.env.*',
     '.DS_Store',
     'Thumbs.db',
+    // Compiler cache: rewritten by every local build, so it would make a new
+    // revision out of nothing.
+    'tsconfig.tsbuildinfo',
 ];
 const IGNORE_FILE = '.xflowignore';
 function globToRegExpSource(pattern) {

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.2.0';
+exports.CLI_VERSION = '0.3.1';
 /** Overridden by XFLOW_API_URL or the `api` field in xflow.json. */
 exports.DEFAULT_API_URL = 'https://app.getxflow.com';

package/dist/zip.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZipError = void 0;
 exports.zipCreate = zipCreate;
+exports.dropDirectoryEntries = dropDirectoryEntries;
 exports.zipRead = zipRead;
 const node_zlib_1 = require("node:zlib");
 class ZipError extends Error {
@@ -122,6 +123,25 @@ function isSafeEntryPath(path) {
     }
     return path.split('/').every((part) => part !== '' && part !== '.' && part !== '..');
 }
+/**
+ * Drop entries whose name is a directory elsewhere in the same archive: old
+ * revisions carry folders as empty files, and unpacking them collides with the
+ * directory of the same name. Call it before writing to disk, not inside
+ * zipRead: the tree hash is checked against the archive as the server made it.
+ */
+function dropDirectoryEntries(entries) {
+    const directories = new Set();
+    for (const entry of entries) {
+        const segments = entry.path.split('/');
+        segments.pop();
+        let current = '';
+        for (const segment of segments) {
+            current = current ? `${current}/${segment}` : segment;
+            directories.add(current);
+        }
+    }
+    return entries.filter((entry) => !directories.has(entry.path));
+}
 function zipRead(buffer) {
     if (buffer.length < 22)
         throw new ZipError('The file is too small to be a zip');

package/package.json

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

package/skills/xflow/SKILL.md

@@ -103,6 +103,30 @@ Interface rules, checked outside `src/components/ui` and `src/components/blocks`
   `react-hot-toast`, `react-dnd`) must have it mounted in `App.tsx`. Missing providers
   build fine and give visitors a white screen.
 
+Template integrity. The app grows out of the platform template, and part of that template
+is not yours to change. The reference is a snapshot of the project itself, taken when the
+platform first looked at it, so these rules never argue with work that was already there:
+
+- Platform files must stay byte for byte as they arrived: `src/lib/theme-sync.ts`,
+  `src/lib/platform-auth.ts`, `src/contexts/platform-auth-context.tsx`,
+  `src/hooks/use-platform-auth.ts`, `src/utils/error-logger.ts`, `src/lib/xflow.ts`.
+  They wire the app to the platform, and every way they break is a silent one. Build what
+  you need around them, never inside them.
+- The entry point keeps calling `initThemeSync()`, `initPlatformAuth()` and
+  `initErrorLogger()`, keeps importing `index.css` and keeps mounting `ThemeProvider`.
+  How the file is written is up to you.
+- `index.html` keeps the element with `id="root"` and the script that loads `src/main`.
+- Theme token names in `src/index.css` stay declared, in `:root` and in `.dark` alike, and
+  the Tailwind config keeps mapping them. Change the values as much as the design needs:
+  it is the names that components paint with.
+- The Tailwind `content` globs keep covering `src/**`. Narrow them and Tailwind strips
+  every class the app uses.
+- Files under `src/components/ui` and `src/components/blocks` may be edited freely but
+  not deleted.
+
+A rejection names the file and the revision to take the original from:
+`xflow pull --revision N --into ./original`, then copy the file back.
+
 ## Cloud functions
 
 Server-side code lives in `functions/<name>/index.ts` and exports `handler`. There is no
@@ -122,13 +146,53 @@ output of that call. Only failed calls are logged, so an empty output means the
 never crashed, not that logging is broken.
 
 From the app, call a function through `src/lib/xflow.ts`:
-`await xflow.functions.invoke('send-mail', { body: { to } })`. It carries the project
-token for you. Addresses are baked into the build, which is why the functions go out first:
+`await xflow.functions.invoke('send-mail', { body: { to } })`. It carries the credentials
+for you. Addresses are baked into the build, which is why the functions go out first:
 by the time the bundle is built they already exist, and a new function is never missing
 from the application that calls it.
 
-Treat a function as a public API: the token ships inside the frontend bundle, so anyone
-who opens the app can call it.
+### Who is calling
+
+A function answers only to a member of the organization who has access to that project.
+The platform issues a short-lived pass when it opens the application, the wrapper checks it
+with the platform on every call, and the handler receives the answer in `event.xflow`:
+
+```js
+exports.handler = async (event) => {
+  const { caller, user } = event.xflow
+  // caller: 'visitor' (a person), 'service' (another function of this project),
+  //         'external' (an outside service with a key), 'schedule' (a timer run)
+  // user:   { id, role } for a visitor, null for everything else
+}
+```
+
+Never trust an identity that arrives in the body or in a header of the request: those are
+written by the page, which lives on someone else's computer. `event.xflow` is the only
+identity the platform stands behind, and `usePlatformAuth()` in the frontend is a hint for
+the interface, not a check.
+
+A function that changes data should say so instead of checking the role by hand:
+
+```js
+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.
+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.
+
+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
+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.
 
 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
@@ -136,8 +200,9 @@ functions read but the platform does not have. Values never come back out — th
 they exist is inside the running function.
 
 A function receives only the variables it mentions by name via `process.env.NAME`, so never
-assemble a variable name from an expression. New values arrive on the next `xflow deploy`,
-not at the moment they are written.
+assemble a variable name from an expression and never destructure the environment
+(`const { API_KEY } = process.env` reads as no mention at all, and the variable arrives
+empty). New values arrive on the next `xflow deploy`, not at the moment they are written.
 
 To run a function on a timer: `xflow schedules set report "0 3 ? * * *"` (daily at 03:00).
 Six fields, UTC, and exactly one of day-of-month / day-of-week must be `?` — that is
@@ -160,7 +225,9 @@ 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.
+You never write that variable yourself: `xflow env set DATABASE_URL=...` is refused. The same
+goes for every name starting with `XFLOW`: the platform fills those in itself, and your value
+under one of them would shadow the real one.
 
 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
@@ -171,6 +238,35 @@ One logical database can be shared by several projects, so your migration can br
 you do not see. `xflow db status` lists applied migrations that have no file in your
 repository: that is what someone else's project did.
 
+## File storage
+
+The project has file storage, and the browser cannot reach it. Those endpoints take only the
+server key of the project, and the platform puts it into the environment of your cloud
+functions as `XFLOW_SERVER_KEY`. Nothing else holds it: not the bundle, not `.env`, not
+`xflow env`.
+
+So uploading is a function of your own. It asks the platform for a one-time link, the browser
+then sends the bytes straight to storage, and a second call records the file:
+
+```js
+const link = await fetch(`${process.env.XFLOW_API_URL}/api/storage/project/upload-url`, {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-Server-Key': process.env.XFLOW_SERVER_KEY,
+  },
+  body: JSON.stringify({ fileName, fileSize, contentType, folderPath: 'invoices' }),
+}).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.
+
+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
+send it to the frontend: the build gate stops on a key found in the application code, and a
+key that reached a visitor lets them delete every file of the project.
+
 ## Syncing code
 
 `xflow status` shows how the local copy differs from the server revision.
@@ -209,8 +305,7 @@ The platform design system already ships inside the project, and the app is supp
 to look like a part of the platform:
 
 - `src/components/ui` for primitives: buttons, inputs, dialogs, tables, menus
-- `src/components/blocks` for composed blocks: `data-table`, `entity-form`,
-  `filter-bar`, `detail-panel`, `kanban`, `charts`, `user-picker`, `relation-picker`
+- `src/components/blocks` for composed blocks: `data-table` and `charts`
 - `src/index.css` for color tokens
 
 Before writing your own component, check whether a block already covers it: props are
@@ -221,7 +316,9 @@ the design system sits in the project.
 
 The app runs inside the platform in an iframe and receives the theme and the current
 user from it. The `usePlatformAuth()` hook gives the name, role, permissions and the
-list of organization members: that is what `user-picker` is built on.
+list of organization members. Use it to draw the interface, never to guard data: the
+value lives on the page and is edited from the console. Guard data in the function, by
+`event.xflow`.
 
 ## Errors from a deployed app
 
@@ -233,6 +330,10 @@ records per project are kept.
 Local `npm run dev` does not report anything: these logs exist for what you cannot open
 in your own devtools.
 
+Cloud functions do work under `npm run dev`, and nothing has to be configured for that:
+the dev server swaps the access key of the logged-in developer for the same narrow pass and
+forwards the call. If it answers that the key is missing, the fix is `xflow login`.
+
 ## Environment
 
 `VITE_XFLOW_PROJECT_TOKEN` and `VITE_XFLOW_API_URL` are written by the CLI when the