@getxflow/cli 0.3.2 → 0.4.0

package/dist/bin.js

@@ -60,7 +60,7 @@ async function run(args) {
             }
             throw new errors_1.CliError(`Unknown command: projects ${second}`, 'Available: list and get');
         case 'skills':
-            (0, skills_1.skills)(rest);
+            await (0, skills_1.skills)(rest);
             return;
         case 'mcp':
             if (second === undefined || second === 'install') {

package/dist/commands/skills.js

@@ -7,18 +7,22 @@ const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const args_1 = require("../args");
 const errors_1 = require("../errors");
+const prompt_1 = require("../prompt");
 const ui_1 = require("../ui");
-/**
- * The SKILL.md format is shared across tools (agentskills.io); each agent reads
- * its own folder. Cursor reads .cursor/rules/*.mdc instead, so it gets the same
- * text under its own header.
- */
-const SKILL_DIRS = [
-    ['.claude', 'skills'],
-    ['.agents', 'skills'],
+const AGENTS = [
+    { id: 'claude', label: 'Claude Code', project: ['.claude', 'skills'], global: ['.claude', 'skills'] },
+    { id: 'cursor', label: 'Cursor', project: ['.agents', 'skills'], global: ['.cursor', 'skills'], rule: true },
+    { id: 'codex', label: 'Codex', project: ['.agents', 'skills'], global: ['.codex', 'skills'] },
+    { id: 'copilot', label: 'GitHub Copilot', project: ['.agents', 'skills'], global: ['.copilot', 'skills'] },
+    { id: 'gemini', label: 'Gemini CLI', project: ['.agents', 'skills'], global: ['.gemini', 'skills'] },
+    { id: 'opencode', label: 'OpenCode', project: ['.agents', 'skills'], global: ['.config', 'opencode', 'skills'] },
+    { id: 'windsurf', label: 'Windsurf', project: ['.windsurf', 'skills'], global: ['.codeium', 'windsurf', 'skills'] },
+    { id: 'openclaw', label: 'OpenClaw', project: ['skills'], global: ['.openclaw', 'skills'] },
+    { id: 'universal', label: 'Other agents (Cline, Warp, Zed, Amp)', project: ['.agents', 'skills'], global: ['.agents', 'skills'] },
 ];
-/** Codex reads its global skills from .codex/skills, not from .agents. */
-const GLOBAL_SKILL_DIRS = [...SKILL_DIRS, ['.codex', 'skills']];
+/** What init and link lay down, and what a run without questions refreshes. */
+const DEFAULT_PROJECT = ['claude', 'cursor', 'codex'];
+const DEFAULT_GLOBAL = ['claude', 'codex', 'universal'];
 const CURSOR_RULE = ['.cursor', 'rules', 'xflow.mdc'];
 /** AGENTS.md is always read, unlike the lazily loaded skill: a short pointer lives there. */
 const POINTER_MARKER = '<!-- xflow-skill -->';
@@ -44,14 +48,20 @@ function cursorRule(skill) {
     const body = skill.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '');
     return `---\ndescription: ${description}\nalwaysApply: false\n---\n\n${body}`;
 }
-/** Writes only when the content differs. Returns the touched path. */
+function skillPath(base, agent, global) {
+    return (0, node_path_1.join)(global ? (0, node_os_1.homedir)() : base, ...(global ? agent.global : agent.project), 'xflow', 'SKILL.md');
+}
+function installed(base, agent, global) {
+    return (0, node_fs_1.existsSync)(skillPath(base, agent, global));
+}
+/** Writes only when the content differs. */
 function writeIfChanged(path, content) {
     const before = (0, node_fs_1.existsSync)(path) ? (0, node_fs_1.readFileSync)(path, 'utf-8') : null;
     if (before === content)
         return null;
     (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
     (0, node_fs_1.writeFileSync)(path, content, 'utf-8');
-    return path;
+    return before === null ? 'new' : 'updated';
 }
 /** Append once, by marker: the file belongs to the user. */
 function appendPointer(base) {
@@ -60,31 +70,48 @@ function appendPointer(base) {
     if (before?.includes(POINTER_MARKER))
         return null;
     (0, node_fs_1.writeFileSync)(path, before ? `${before.replace(/\s*$/, '')}\n\n${POINTER}` : POINTER, 'utf-8');
-    return path;
+    return { path, state: before === null ? 'new' : 'updated' };
 }
-function install(base, global) {
+function install(base, ids, global) {
     const skill = skillSource();
-    const touched = [];
-    for (const dir of global ? GLOBAL_SKILL_DIRS : SKILL_DIRS) {
-        const path = writeIfChanged((0, node_path_1.join)(base, ...dir, 'xflow', 'SKILL.md'), skill);
-        if (path)
-            touched.push(path);
+    const changes = [];
+    const seen = new Set();
+    const put = (path, content) => {
+        if (seen.has(path))
+            return;
+        seen.add(path);
+        const state = writeIfChanged(path, content);
+        if (state)
+            changes.push({ path, state });
+    };
+    for (const agent of AGENTS) {
+        if (!ids.includes(agent.id))
+            continue;
+        put(skillPath(base, agent, global), skill);
+        if (!global && agent.rule === true)
+            put((0, node_path_1.join)(base, ...CURSOR_RULE), cursorRule(skill));
     }
     // Project-level only: these have no global equivalents.
     if (!global) {
-        const rule = writeIfChanged((0, node_path_1.join)(base, ...CURSOR_RULE), cursorRule(skill));
-        if (rule)
-            touched.push(rule);
         const pointer = appendPointer(base);
         if (pointer)
-            touched.push(pointer);
+            changes.push(pointer);
     }
-    return touched;
+    return changes;
+}
+/** Defaults plus whatever is already installed, so an update run refreshes everything. */
+function defaultIds(base, global) {
+    const ids = new Set(global ? DEFAULT_GLOBAL : DEFAULT_PROJECT);
+    for (const agent of AGENTS) {
+        if (installed(base, agent, global))
+            ids.add(agent.id);
+    }
+    return [...ids];
 }
 /** Best-effort install from init and link: a failure must not break the linking. */
 function installSkillQuietly(base) {
     try {
-        if (install(base, false).length > 0) {
+        if (install(base, defaultIds(base, false), false).length > 0) {
             (0, ui_1.note)((0, ui_1.dim)('  The platform instructions are laid out for the AI agent'));
         }
     }
@@ -92,12 +119,86 @@ function installSkillQuietly(base) {
         (0, ui_1.note)((0, ui_1.dim)('  Could not lay out the AI agent instructions: xflow skills'));
     }
 }
-function skills(args) {
-    const global = (0, args_1.flagBool)(args, 'global');
-    const touched = install(global ? (0, node_os_1.homedir)() : process.cwd(), global);
-    for (const path of touched)
-        (0, ui_1.out)(path);
-    if (touched.length === 0)
+function pathLabel(agent, global) {
+    const dir = global ? agent.global : agent.project;
+    return (global ? ['~', ...dir] : dir).join('/');
+}
+function listAgents(base) {
+    (0, ui_1.table)(AGENTS.map((agent) => [
+        agent.id,
+        agent.label,
+        pathLabel(agent, false) + (installed(base, agent, false) ? ' *' : ''),
+        pathLabel(agent, true) + (installed(base, agent, true) ? ' *' : ''),
+    ]));
+    (0, ui_1.note)((0, ui_1.dim)('  * installed. Columns: id, agent, in the project, in the home folder'));
+    (0, ui_1.note)((0, ui_1.dim)('  Install without questions: xflow skills --agent <id,id> [--global]'));
+}
+async function pick(globalFlag) {
+    let global = globalFlag;
+    if (!globalFlag) {
+        const scope = await (0, prompt_1.select)('Where to install the xflow skill', [
+            { label: 'This project', hint: process.cwd() },
+            { label: 'Globally', hint: 'home folder, visible to every project' },
+        ]);
+        if (scope === null)
+            return null;
+        global = scope === 1;
+    }
+    const base = process.cwd();
+    const present = AGENTS.map((agent) => installed(base, agent, global));
+    const anyPresent = present.includes(true);
+    const defaults = global ? DEFAULT_GLOBAL : DEFAULT_PROJECT;
+    const picked = await (0, prompt_1.multiSelect)('Which agents get the skill', AGENTS.map((agent, i) => ({
+        label: agent.label,
+        hint: pathLabel(agent, global) + (present[i] ? ', installed' : ''),
+        checked: anyPresent ? present[i] : defaults.includes(agent.id),
+    })));
+    if (picked === null || picked.length === 0)
+        return null;
+    return { ids: picked.map((i) => AGENTS[i].id), global };
+}
+async function skills(args) {
+    const sub = args.words[0];
+    if (sub === 'list') {
+        listAgents(process.cwd());
+        return;
+    }
+    if (sub !== undefined) {
+        throw new errors_1.CliError(`Unknown command: skills ${sub}`, 'Available: xflow skills [list]');
+    }
+    let global = (0, args_1.flagBool)(args, 'global');
+    const agentFlag = (0, args_1.flagString)(args, 'agent');
+    if (args.flags.agent !== undefined && agentFlag === undefined) {
+        throw new errors_1.CliError('The --agent flag needs a value', 'For example: --agent claude,cursor. The ids: xflow skills list');
+    }
+    let ids;
+    if (agentFlag !== undefined) {
+        ids = agentFlag
+            .split(',')
+            .map((id) => id.trim())
+            .filter((id) => id.length > 0);
+        const known = new Set(AGENTS.map((agent) => agent.id));
+        const unknown = ids.filter((id) => !known.has(id));
+        if (unknown.length > 0 || ids.length === 0) {
+            throw new errors_1.CliError(unknown.length > 0 ? `Unknown agent: ${unknown.join(', ')}` : 'No agents named', 'The ids: xflow skills list');
+        }
+    }
+    else if (process.stdin.isTTY === true && process.stderr.isTTY === true && !(0, args_1.flagBool)(args, 'yes')) {
+        const picked = await pick(global);
+        if (picked === null) {
+            (0, ui_1.note)((0, ui_1.dim)('  nothing chosen, nothing changed'));
+            return;
+        }
+        ids = picked.ids;
+        global = picked.global;
+    }
+    else {
+        ids = defaultIds(process.cwd(), global);
+    }
+    const changes = install(process.cwd(), ids, global);
+    for (const change of changes)
+        (0, ui_1.out)(`${change.state === 'new' ? '+' : '~'} ${change.path}`);
+    if (changes.length === 0)
         (0, ui_1.note)((0, ui_1.dim)('  everything is already up to date'));
     (0, ui_1.ok)(global ? 'The xflow skill is available in every project' : 'The xflow skill is in place');
     (0, ui_1.note)((0, ui_1.dim)('  After a CLI update run the command again: the skill ships with it'));

package/dist/help.js

@@ -16,7 +16,7 @@ ${(0, ui_1.bold)('Getting started')}
   xflow init [dir]                new project from the platform template
   xflow templates                 which templates are available
   xflow link <id>                 link this folder to a project (id: xflow projects list)
-  xflow skills [--global]         refresh the platform instructions for an AI agent
+  xflow skills                    pick the agents that get the platform instructions
   xflow mcp install               give the agent platform access without a terminal
 
 ${(0, ui_1.bold)('Code')}
@@ -183,19 +183,23 @@ project from the ${(0, ui_1.bold)('project_id')} argument, not from your folder,
 An agent has no way to know about XFlow: the platform is not in its training. The
 instructions explain how to release and publish, where the design system components
 come from, and where to look for production errors. ${(0, ui_1.bold)('init')} and ${(0, ui_1.bold)('link')} lay them
-down on their own, so this command is for refreshing them after a CLI update: the two
-ship as one version.
-
-The format is shared (agentskills.io) but the folders differ per tool, so we write all:
-
-  .claude/skills/xflow/SKILL.md    Claude Code
-  .agents/skills/xflow/SKILL.md    Codex, OpenClaw
-  .cursor/rules/xflow.mdc          Cursor: it does not read the shared format
-
-  --global    the same in the home folder, which makes the skill visible in every
-              project. There ~/.codex/skills is added as well, because Codex looks in
-              its shared catalog only inside a repository. The Cursor rule and
-              AGENTS.md stay per project, they have no global counterpart
+down on their own for the common agents, so this command exists to pick tools
+precisely and to refresh after a CLI update: the skill and the CLI ship as one version.
+
+Run in a terminal, it asks two questions: where (this project, or the home folder,
+which makes the skill visible in every project) and for which agents. Copies that are
+already installed come pre-selected and are updated in place. Without a terminal, in
+CI or when an agent runs the command, there are no questions: the defaults plus every
+already installed copy are refreshed.
+
+  xflow skills list               the agents, their folders and what is installed
+  --agent claude,cursor           exact agents, no questions asked
+  --global                        the home folder instead of the project
+  --yes                           no questions: defaults plus what is installed
+
+The format is shared (agentskills.io) and inside a project most tools read the shared
+.agents/skills folder, so the paths differ mostly in the home directory. Cursor also
+gets .cursor/rules/xflow.mdc: its older versions do not read the shared format.
 
 Plus a few pointer lines in ${(0, ui_1.bold)('AGENTS.md')}. A skill is picked up lazily, only when its
 description matches the task, and "add a customers table" will not trigger it. AGENTS.md

package/dist/prompt.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.multiSelect = multiSelect;
+exports.select = select;
+const node_readline_1 = require("node:readline");
+const errors_1 = require("./errors");
+const ui_1 = require("./ui");
+function render(lines, first) {
+    const up = first ? '' : `[${lines.length}A`;
+    process.stderr.write(up + lines.map((line) => `${line}\n`).join(''));
+}
+function listen(onKey) {
+    if (process.stdin.isTTY !== true) {
+        throw new errors_1.CliError('An interactive prompt needs a terminal', 'Pass the choice through flags instead');
+    }
+    (0, node_readline_1.emitKeypressEvents)(process.stdin);
+    const wasRaw = process.stdin.isRaw === true;
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    const handler = (_, key) => {
+        if (key)
+            onKey(key);
+    };
+    process.stdin.on('keypress', handler);
+    return () => {
+        process.stdin.off('keypress', handler);
+        process.stdin.setRawMode(wasRaw);
+        process.stdin.pause();
+    };
+}
+const isConfirm = (key) => key.name === 'return' || key.name === 'enter';
+const isCancel = (key) => key.name === 'escape' || (key.ctrl === true && key.name === 'c');
+/** Checkbox list. Resolves with the picked indexes, or null when cancelled. */
+function multiSelect(title, choices) {
+    return new Promise((resolve) => {
+        let cursor = 0;
+        let first = true;
+        const checked = choices.map((choice) => choice.checked === true);
+        const draw = () => {
+            render([
+                (0, ui_1.bold)(title),
+                ...choices.map((choice, i) => {
+                    const hint = choice.hint ? `  ${(0, ui_1.dim)(choice.hint)}` : '';
+                    return `${i === cursor ? '>' : ' '} ${checked[i] ? '[x]' : '[ ]'} ${choice.label}${hint}`;
+                }),
+                (0, ui_1.dim)('  up/down move, space toggle, enter confirm, esc cancel'),
+            ], first);
+            first = false;
+        };
+        const stop = listen((key) => {
+            if (key.name === 'up')
+                cursor = (cursor + choices.length - 1) % choices.length;
+            else if (key.name === 'down')
+                cursor = (cursor + 1) % choices.length;
+            else if (key.name === 'space')
+                checked[cursor] = !checked[cursor];
+            else if (isConfirm(key)) {
+                stop();
+                resolve(checked.flatMap((on, i) => (on ? [i] : [])));
+                return;
+            }
+            else if (isCancel(key)) {
+                stop();
+                resolve(null);
+                return;
+            }
+            else
+                return;
+            draw();
+        });
+        draw();
+    });
+}
+/** Radio list. Resolves with the picked index, or null when cancelled. */
+function select(title, choices) {
+    return new Promise((resolve) => {
+        let cursor = 0;
+        let first = true;
+        const draw = () => {
+            render([
+                (0, ui_1.bold)(title),
+                ...choices.map((choice, i) => {
+                    const hint = choice.hint ? `  ${(0, ui_1.dim)(choice.hint)}` : '';
+                    return `${i === cursor ? '>' : ' '} ${choice.label}${hint}`;
+                }),
+                (0, ui_1.dim)('  up/down move, enter confirm, esc cancel'),
+            ], first);
+            first = false;
+        };
+        const stop = listen((key) => {
+            if (key.name === 'up')
+                cursor = (cursor + choices.length - 1) % choices.length;
+            else if (key.name === 'down')
+                cursor = (cursor + 1) % choices.length;
+            else if (isConfirm(key)) {
+                stop();
+                resolve(cursor);
+                return;
+            }
+            else if (isCancel(key)) {
+                stop();
+                resolve(null);
+                return;
+            }
+            else
+                return;
+            draw();
+        });
+        draw();
+    });
+}

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.4.0';
 /** 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.2",
+  "version": "0.4.0",
   "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
 
@@ -16,6 +17,26 @@ memory. If a command is not in the help output, it does not exist: guessing flag
 pointless. The CLI prints a hint with almost every error, read it in full, it usually
 contains the fix.
 
+## Hard rules
+
+These mistakes cost the most because nothing fails at the moment they are made, or
+the error points away from the cause. The sections below carry the details.
+
+1. Read environment variables literally: `process.env.API_KEY`. Destructuring
+   (`const { API_KEY } = process.env`) reads as no mention of the variable at all,
+   and it arrives empty.
+2. A value written with `xflow env set` reaches the functions on the next
+   `xflow deploy`, not at the moment it is written.
+3. Never delete a `functions/<name>/` directory unless the user asked for that
+   function to go. The next deploy removes it from the cloud together with its
+   schedules, and a function created again later gets a different address.
+4. An already applied migration is never re-run, so editing its file changes
+   nothing. A schema change is always a new file.
+5. When inserts start failing with `db_write_locked`, the database is over its plan
+   size. The fix is a migration that deletes data, never a rewrite of the failing SQL.
+6. In file storage, call `confirm` only after the PUT has finished, and send the same
+   `Content-Type` in both calls. Both mistakes answer 200 and break later.
+
 ## Plan limits
 
 The organization runs on a plan with finite limits: projects, cloud functions, developer
@@ -134,6 +155,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
@@ -215,6 +242,17 @@ To run a function on a timer: `xflow schedules set report "0 3 ? * * *"` (daily
 Six fields, UTC, and exactly one of day-of-month / day-of-week must be `?` — that is
 how Yandex wants it. A scheduled run reaches the handler as a POST with no headers.
 
+The pieces line up in one pass. From a new function to a verified schedule:
+
+```
+xflow env set SMTP_PASSWORD=...            # secrets first: values ride the next deploy
+# write functions/report/index.ts, reading process.env.SMTP_PASSWORD literally
+xflow deploy                               # ships the function, then builds the app
+xflow schedules set report "0 3 ? * * *"   # after the deploy: a schedule needs a deployed function
+xflow functions invoke report              # run it once, the way the app would
+xflow functions logs report                # empty output means it never crashed
+```
+
 ## Database
 
 Schema changes are files: `migrations/0001_init.sql`, `migrations/0002_orders.sql`, applied
@@ -291,6 +329,10 @@ answers you get:
   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
 send it to the frontend: the build gate stops on a key found in the application code, and a