@getxflow/cli 0.5.1 → 0.6.1

package/README.md

@@ -30,13 +30,15 @@ else's code belongs next to it.
 | `projects list` / `projects get` / `open` | projects of the organization and the application addresses |
 | `skills` | platform instructions for an AI agent ([Agent Skills](https://agentskills.io) format) |
 | `mcp install` | connect the agent to the platform directly, without a terminal |
+| `update` | update the CLI itself, and the skill that ships inside it |
 
 Help for one command: `xflow help <command>`.
 
 You write the application yourself or with your agent: the platform stays out of the code.
 `xflow skills` puts a description of the platform alongside it, which Claude Code, Codex and
 OpenClaw pick up on their own when a task touches XFlow. Your `AGENTS.md` and `CLAUDE.md` are
-left alone.
+left alone. The description ships inside the package and shares its version, so `xflow update`
+brings both.
 
 `xflow mcp install` connects the agent to the platform directly: the database, migrations,
 functions, schedules, variables and versions become its tools, with no command output to parse.

package/dist/api.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ApiError = void 0;
+exports.newerVersionSeen = newerVersionSeen;
 exports.apiJson = apiJson;
 exports.apiBinary = apiBinary;
 exports.apiUpload = apiUpload;
@@ -48,10 +49,18 @@ function isOlder(current, required) {
     }
     return false;
 }
+let newerVersion = null;
+/** The published version the platform reported, if it is newer than this copy. */
+function newerVersionSeen() {
+    return newerVersion;
+}
 function assertProtocol(response) {
+    const latest = response.headers.get('x-xflow-cli-latest');
+    if (latest && isOlder(version_1.CLI_VERSION, latest))
+        newerVersion = latest;
     const required = response.headers.get('x-xflow-cli-min');
     if (required && isOlder(version_1.CLI_VERSION, required)) {
-        throw new ApiError(`The platform requires CLI ${required} or newer, ${version_1.CLI_VERSION} is installed`, 'outdated_cli', response.status, 'Update: npm i -g @getxflow/cli');
+        throw new ApiError(`The platform requires CLI ${required} or newer, ${version_1.CLI_VERSION} is installed`, 'outdated_cli', response.status, 'Run: xflow update');
     }
 }
 async function send(client, path, options = {}) {

package/dist/args.js

@@ -13,6 +13,7 @@ const BOOLEAN_FLAGS = new Set([
     'help',
     'version',
     'global',
+    'refresh',
     'live',
     'no-push',
     'skip-build',

package/dist/bin.js

@@ -7,6 +7,7 @@ const config_1 = require("./config");
 const errors_1 = require("./errors");
 const help_1 = require("./help");
 const limits_1 = require("./limits");
+const state_1 = require("./state");
 const ui_1 = require("./ui");
 const zip_1 = require("./zip");
 const version_1 = require("./version");
@@ -21,6 +22,7 @@ const schedules_1 = require("./commands/schedules");
 const skills_1 = require("./commands/skills");
 const sources_1 = require("./commands/sources");
 const deploy_1 = require("./commands/deploy");
+const update_1 = require("./commands/update");
 async function run(args) {
     const [first, second] = args.words;
     const rest = { ...args, words: args.words.slice(1) };
@@ -156,10 +158,25 @@ async function run(args) {
         case 'deployments':
             await (0, deploy_1.deployments)();
             return;
+        case 'update':
+            (0, update_1.update)();
+            return;
         default:
             throw new errors_1.CliError(`Unknown command: ${first}`, 'The list of commands: xflow help');
     }
 }
+/**
+ * The platform reports the published version on every response, so this costs no
+ * request. One line, after the command has had its say, and at most once a day:
+ * an agent runs a dozen commands per session and cannot act on twelve reminders.
+ */
+function nudge() {
+    const latest = (0, api_1.newerVersionSeen)();
+    if (latest === null || !(0, state_1.shouldNudge)(latest))
+        return;
+    (0, ui_1.note)((0, ui_1.dim)(`  xflow ${latest} is out, ${version_1.CLI_VERSION} is installed: run xflow update`));
+    (0, state_1.markNudged)(latest);
+}
 async function main() {
     const args = (0, args_1.parseArgs)(process.argv.slice(2));
     if ((0, args_1.flagBool)(args, 'version')) {
@@ -170,6 +187,9 @@ async function main() {
         (0, help_1.help)(args.words[0]);
         return 0;
     }
+    // The update command says it better itself, and the min-version refusal already
+    // carries the same advice in its hint.
+    let quiet = args.words[0] === 'update';
     try {
         await run(args);
         return 0;
@@ -181,6 +201,7 @@ async function main() {
                 (0, ui_1.note)((0, ui_1.dim)(`  ${(0, limits_1.limitLine)(e.limit)}`));
             if (e.hint)
                 (0, ui_1.note)((0, ui_1.dim)(`  ${e.hint}`));
+            quiet = quiet || e.code === 'outdated_cli';
             return 1;
         }
         if (e instanceof errors_1.CliError || e instanceof config_1.ConfigError || e instanceof zip_1.ZipError) {
@@ -195,6 +216,10 @@ async function main() {
             (0, ui_1.note)((0, ui_1.dim)(e.stack));
         return 1;
     }
+    finally {
+        if (!quiet)
+            nudge();
+    }
 }
 main().then((code) => {
     process.exitCode = code;

package/dist/commands/mcp.js

@@ -1,13 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mcpInstall = mcpInstall;
-const node_child_process_1 = require("node:child_process");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const api_1 = require("../api");
 const args_1 = require("../args");
 const config_1 = require("../config");
 const session_1 = require("../session");
+const spawn_1 = require("../spawn");
 const ui_1 = require("../ui");
 /** Clients with their own server-add command. */
 const CLIENTS = [
@@ -28,23 +28,10 @@ const CLIENTS = [
         reset: ['mcp', 'remove', 'xflow', '-s', 'local'],
     },
 ];
-const WINDOWS = process.platform === 'win32';
-/**
- * Windows needs a shell to resolve npm's .cmd shims, and the shell joins
- * arguments instead of escaping them: quote by hand.
- */
-function quote(value) {
-    return WINDOWS ? `"${value.replace(/"/g, '""')}"` : value;
-}
-function execute(binary, args) {
-    // Capture output: clients may echo the added header together with the key.
-    const options = { encoding: 'utf-8' };
-    return WINDOWS
-        ? (0, node_child_process_1.spawnSync)([binary, ...args.map(quote)].join(' '), { ...options, shell: true })
-        : (0, node_child_process_1.spawnSync)(binary, args, options);
-}
+// Output is captured, not inherited: clients may echo the added header together
+// with the key.
 function hasBinary(binary) {
-    return execute(binary, ['--version']).status === 0;
+    return (0, spawn_1.run)(binary, ['--version']).status === 0;
 }
 async function mcpInstall(args) {
     // The server covers the organization: the command works outside a project folder too.
@@ -62,8 +49,8 @@ async function mcpInstall(args) {
             continue;
         found++;
         (0, ui_1.step)(`Writing into ${target.label}`);
-        execute(target.binary, [...target.reset]);
-        const result = execute(target.binary, target.args(url, client.token));
+        (0, spawn_1.run)(target.binary, [...target.reset]);
+        const result = (0, spawn_1.run)(target.binary, target.args(url, client.token));
         if (result.status === 0) {
             installed++;
             (0, ui_1.ok)(`${target.label}: the xflow server is connected`);

package/dist/commands/skills.js

@@ -99,6 +99,33 @@ function install(base, ids, global) {
     }
     return changes;
 }
+/**
+ * Rewrite every copy that already exists and create none: this is what xflow update
+ * calls, and it runs wherever the user happened to stand. Installing defaults here
+ * would litter a random folder with .claude, .agents and an AGENTS.md.
+ */
+function refreshInstalled(base) {
+    const skill = skillSource();
+    const changes = [];
+    const seen = new Set();
+    const put = (path, content) => {
+        if (seen.has(path) || !(0, node_fs_1.existsSync)(path))
+            return;
+        seen.add(path);
+        const state = writeIfChanged(path, content);
+        if (state)
+            changes.push({ path, state });
+    };
+    for (const agent of AGENTS) {
+        put(skillPath(base, agent, false), skill);
+        put(skillPath(base, agent, true), skill);
+        // The Cursor rule is not one of the agent paths: without this line it keeps the
+        // old text next to a fresh SKILL.md, and the two drift apart unnoticed.
+        if (agent.rule === true)
+            put((0, node_path_1.join)(base, ...CURSOR_RULE), cursorRule(skill));
+    }
+    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);
@@ -163,6 +190,16 @@ async function skills(args) {
         listAgents(process.cwd());
         return;
     }
+    if ((0, args_1.flagBool)(args, 'refresh')) {
+        const refreshed = refreshInstalled(process.cwd());
+        for (const change of refreshed)
+            (0, ui_1.out)(`~ ${change.path}`);
+        if (refreshed.length === 0)
+            (0, ui_1.note)((0, ui_1.dim)('  nothing installed here, nothing to refresh'));
+        else
+            (0, ui_1.ok)('The xflow skill matches the CLI');
+        return;
+    }
     if (sub !== undefined) {
         throw new errors_1.CliError(`Unknown command: skills ${sub}`, 'Available: xflow skills [list]');
     }
@@ -201,5 +238,5 @@ async function skills(args) {
     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'));
+    (0, ui_1.note)((0, ui_1.dim)('  The skill ships with the CLI: xflow update brings both'));
 }

package/dist/commands/update.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyPath = classifyPath;
+exports.update = update;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const errors_1 = require("../errors");
+const spawn_1 = require("../spawn");
+const ui_1 = require("../ui");
+const version_1 = require("../version");
+const PACKAGE = '@getxflow/cli';
+const WINDOWS = process.platform === 'win32';
+function classifyPath(dir) {
+    const parts = dir.split(/[\\/]/).map((part) => part.toLowerCase());
+    if (parts.includes('_npx'))
+        return 'npx';
+    if (parts.includes('pnpm') || parts.includes('.pnpm'))
+        return 'pnpm';
+    if (parts.includes('.bun'))
+        return 'bun';
+    if (parts.includes('.yarn'))
+        return 'yarn';
+    // A global npm prefix has a node_modules too, so this only separates a source
+    // checkout (npm link, tsx cli/src) from everything installed.
+    if (!parts.includes('node_modules'))
+        return 'checkout';
+    return 'node_modules';
+}
+/**
+ * The manifest of a project that depends on the package, if this copy is such a
+ * dependency. A dependency and a tool need opposite answers: inside npm scripts the
+ * local .bin wins over PATH, so a global install would leave the old version running.
+ */
+function projectManifest(dir) {
+    let current = dir;
+    for (let depth = 0; depth < 12; depth++) {
+        const parent = (0, node_path_1.dirname)(current);
+        if (parent === current)
+            return null;
+        if (current.split(/[\\/]/).pop()?.toLowerCase() === 'node_modules') {
+            const path = (0, node_path_1.join)(parent, 'package.json');
+            if (!(0, node_fs_1.existsSync)(path))
+                return null;
+            try {
+                const pkg = JSON.parse((0, node_fs_1.readFileSync)(path, 'utf-8'));
+                const declared = pkg.dependencies?.[PACKAGE] ?? pkg.devDependencies?.[PACKAGE];
+                return declared === undefined ? null : path;
+            }
+            catch {
+                return null;
+            }
+        }
+        current = parent;
+    }
+    return null;
+}
+function npmRoot() {
+    const result = (0, spawn_1.run)('npm', ['root', '-g'], {
+        timeout: 60_000,
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    if (result.error || result.status !== 0 || typeof result.stdout !== 'string')
+        return null;
+    const dir = result.stdout.trim();
+    return dir.length > 0 && (0, node_fs_1.existsSync)(dir) ? dir : null;
+}
+function packageDir(root) {
+    return (0, node_path_1.join)(root, '@getxflow', 'cli');
+}
+function installedVersion(root) {
+    try {
+        const pkg = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(packageDir(root), 'package.json'), 'utf-8'));
+        return pkg.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The skill ships inside the package and shares its version, so a fresh CLI with a
+ * stale skill is an agent reading last month's instructions. Run through the freshly
+ * installed binary by absolute path: PATH may point at another copy, and this process
+ * still holds the old code in memory.
+ */
+function refreshSkill(root) {
+    const bin = (0, node_path_1.join)(packageDir(root), 'dist', 'bin.js');
+    if (!(0, node_fs_1.existsSync)(bin)) {
+        (0, ui_1.note)((0, ui_1.dim)('  Refresh the agent instructions yourself: xflow skills'));
+        return;
+    }
+    const result = (0, node_child_process_1.spawnSync)(process.execPath, [bin, 'skills', '--refresh'], { stdio: 'inherit' });
+    if (result.error || result.status !== 0) {
+        (0, ui_1.note)((0, ui_1.dim)('  Could not refresh the agent instructions, run xflow skills'));
+    }
+}
+function manual(command, why) {
+    (0, ui_1.note)((0, ui_1.dim)(`  ${why}`));
+    (0, ui_1.note)(`  ${command}`);
+}
+function update() {
+    const kind = classifyPath(__dirname);
+    if (kind === 'checkout') {
+        (0, ui_1.ok)(`xflow ${version_1.CLI_VERSION} runs from a source checkout`);
+        (0, ui_1.note)((0, ui_1.dim)('  Nothing to update here: pull the repository and rebuild'));
+        return;
+    }
+    if (kind === 'npx') {
+        (0, ui_1.ok)(`xflow ${version_1.CLI_VERSION} runs from the npx cache`);
+        manual(`npm i -g ${PACKAGE}@latest`, 'npx keeps its own copy. Install the CLI properly:');
+        return;
+    }
+    if (kind === 'pnpm') {
+        manual(`pnpm add -g ${PACKAGE}@latest`, 'Installed by pnpm, so npm must not touch it:');
+        return;
+    }
+    if (kind === 'bun') {
+        manual(`bun add -g ${PACKAGE}@latest`, 'Installed by bun, so npm must not touch it:');
+        return;
+    }
+    if (kind === 'yarn') {
+        manual(`yarn global add ${PACKAGE}@latest`, 'Installed by yarn, so npm must not touch it:');
+        return;
+    }
+    const manifest = projectManifest(__dirname);
+    if (manifest !== null) {
+        (0, ui_1.ok)(`xflow ${version_1.CLI_VERSION} is a dependency of this project`);
+        manual(`npm i -D ${PACKAGE}@latest`, `Declared in ${manifest}. A global install would change nothing: inside npm scripts the local copy wins`);
+        return;
+    }
+    (0, ui_1.step)(`updating ${PACKAGE} from ${version_1.CLI_VERSION}`);
+    const result = (0, spawn_1.run)('npm', ['i', '-g', `${PACKAGE}@latest`], { stdio: 'inherit' });
+    if (result.error) {
+        throw new errors_1.CliError(`Could not run npm: ${result.error.message}`, `Install by hand: npm i -g ${PACKAGE}@latest`);
+    }
+    if (result.status !== 0) {
+        throw new errors_1.CliError('npm could not install the package', WINDOWS
+            ? 'The npm output is above. Windows also locks the xflow.cmd of a running command: close the other terminals and repeat'
+            : 'The npm output is above. A permission error means the global folder belongs to root: fix npm rather than run it with sudo');
+    }
+    const root = npmRoot();
+    const after = root === null ? null : installedVersion(root);
+    if (root === null || after === null) {
+        (0, ui_1.ok)(`${PACKAGE} installed`);
+        (0, ui_1.note)((0, ui_1.dim)('  Check what is on disk now: xflow --version'));
+        return;
+    }
+    if (after === version_1.CLI_VERSION) {
+        (0, ui_1.ok)(`xflow ${after} is the latest version`);
+        return;
+    }
+    (0, ui_1.ok)(`xflow ${version_1.CLI_VERSION} → ${after}`);
+    refreshSkill(root);
+}

package/dist/commands/update.test.js

@@ -0,0 +1,34 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_test_1 = require("node:test");
+const update_1 = require("./update");
+/**
+ * The price of a mistake here is npm running over a pnpm or bun installation, which
+ * leaves two copies and a user who cannot tell which one answers. Path shapes only,
+ * the rest of the command is a run, not a rule.
+ */
+(0, node_test_1.test)('a global npm prefix is an ordinary install', () => {
+    strict_1.default.equal((0, update_1.classifyPath)('C:\\Users\\me\\AppData\\Roaming\\npm\\node_modules\\@getxflow\\cli\\dist'), 'node_modules');
+    strict_1.default.equal((0, update_1.classifyPath)('/usr/local/lib/node_modules/@getxflow/cli/dist'), 'node_modules');
+    strict_1.default.equal((0, update_1.classifyPath)('/home/me/.npm-global/lib/node_modules/@getxflow/cli/dist'), 'node_modules');
+});
+(0, node_test_1.test)('npm as a path segment is not pnpm', () => {
+    strict_1.default.notEqual((0, update_1.classifyPath)('C:\\Users\\me\\AppData\\Roaming\\npm\\node_modules\\@getxflow\\cli\\dist'), 'pnpm');
+});
+(0, node_test_1.test)('other package managers are recognized by their own folders', () => {
+    strict_1.default.equal((0, update_1.classifyPath)('/home/me/.local/share/pnpm/global/5/node_modules/@getxflow/cli/dist'), 'pnpm');
+    strict_1.default.equal((0, update_1.classifyPath)('/home/me/project/node_modules/.pnpm/@getxflow+cli@0.6.0/node_modules/@getxflow/cli/dist'), 'pnpm');
+    strict_1.default.equal((0, update_1.classifyPath)('/home/me/.bun/install/global/node_modules/@getxflow/cli/dist'), 'bun');
+    strict_1.default.equal((0, update_1.classifyPath)('/home/me/project/.yarn/cache/@getxflow-cli/dist'), 'yarn');
+});
+(0, node_test_1.test)('an npx run is a cached copy, not an installation', () => {
+    strict_1.default.equal((0, update_1.classifyPath)('/home/me/.npm/_npx/8f1a2b/node_modules/@getxflow/cli/dist'), 'npx');
+});
+(0, node_test_1.test)('without node_modules the code runs from a checkout', () => {
+    strict_1.default.equal((0, update_1.classifyPath)('C:\\cursor\\xflow 2.0\\cli\\dist'), 'checkout');
+    strict_1.default.equal((0, update_1.classifyPath)('/home/me/xflow/cli/src'), 'checkout');
+});

package/dist/help.js

@@ -57,6 +57,7 @@ ${(0, ui_1.bold)('Reference')}
   xflow projects get [id]         project card
   xflow whoami                    whose key this is and what it can do
   xflow logout                    forget the key
+  xflow update                    update the CLI itself, and the skill that ships with it
 
 ${(0, ui_1.bold)('Environment')}
   XFLOW_TOKEN                     access key (for CI, instead of xflow login)
@@ -65,6 +66,29 @@ ${(0, ui_1.bold)('Environment')}
 More about one command: xflow help <command>`);
 }
 const TOPICS = {
+    update: `${(0, ui_1.bold)('xflow update')}: bring the CLI up to date
+
+Installs the published version and, if anything changed, rewrites the platform
+instructions the agents already have: the skill ships inside the package and shares
+its version, so a fresh CLI next to a stale skill means the agent is reading last
+month's rules. Copies that are not installed are not created, so it is safe to run
+from any folder.
+
+The platform reports the published version with every answer, which is where the
+${(0, ui_1.bold)('xflow N is out')} line comes from. It appears once a day at most, and never in CI,
+where nobody is going to update anything anyway.
+
+The command works out how this copy was installed from its own path, and refuses to
+cross package managers: an install made by pnpm or bun is printed as their own
+command rather than handed to npm, which would leave you with two copies and no way
+to tell which one answers. Two more cases end the same way. Under ${(0, ui_1.bold)('npx')} there is
+nothing to update, only a cache. And a copy inside a project's node_modules is a
+dependency of that project: ${(0, ui_1.bold)('npm i -D @getxflow/cli@latest')} is the fix, because
+inside npm scripts the local copy wins over anything installed globally.
+
+A refusal from the platform saying the CLI is too old is a different thing: that one
+is a hard gate on a changed contract, and until you run this command nothing else
+will work.`,
     db: `${(0, ui_1.bold)('xflow db')}: schema, data, migrations
 
   xflow db status                  what is applied and what is waiting
@@ -199,7 +223,8 @@ An agent has no way to know about XFlow: the platform is not in its training. Th
 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 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.
+precisely. Refreshing after a CLI update is not your job any more: the skill and the
+CLI ship as one version, and ${(0, ui_1.bold)('xflow update')} rewrites the copies you already have.
 
 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
@@ -211,6 +236,7 @@ already installed copy are refreshed.
   --agent claude,cursor           exact agents, no questions asked
   --global                        the home folder instead of the project
   --yes                           no questions: defaults plus what is installed
+  --refresh                       rewrite the copies that exist, create none
 
 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

package/dist/limits.test.js

@@ -0,0 +1,25 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = require("node:test");
+const strict_1 = __importDefault(require("node:assert/strict"));
+const limits_1 = require("./limits");
+(0, node_test_1.test)('a counted limit reads as a tally', () => {
+    const line = (0, limits_1.limitLine)({ code: 'limit_functions', used: 29, limit: 29 });
+    strict_1.default.equal(line, 'Plan limit: cloud functions, 29 of 29 used. Repeating the same command will not help.');
+});
+(0, node_test_1.test)('an interval reads as a frequency, not as a tally', () => {
+    const line = (0, limits_1.limitLine)({ code: 'limit_schedule_interval', used: 5, limit: 60 });
+    strict_1.default.match(line, /every 5 min against a 60 min minimum/);
+    strict_1.default.doesNotMatch(line, /used/);
+});
+(0, node_test_1.test)('a refusal without numbers stays a plain sentence', () => {
+    const line = (0, limits_1.limitLine)({ code: 'plan_no_schedules' });
+    strict_1.default.equal(line, 'Plan limit: schedules. Repeating the same command will not help.');
+});
+(0, node_test_1.test)('an unknown code falls back to the code itself', () => {
+    const line = (0, limits_1.limitLine)({ code: 'limit_unheard_of' });
+    strict_1.default.match(line, /Plan limit: limit_unheard_of\./);
+});

package/dist/spawn.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = run;
+const node_child_process_1 = require("node:child_process");
+const WINDOWS = process.platform === 'win32';
+/**
+ * Windows resolves npm and other .cmd shims only through a shell, and a shell
+ * together with an args array is what Node deprecated in DEP0190: it joins them
+ * itself, without escaping, and says so in the middle of our output. So the command
+ * line is built and quoted here, and no other platform gets a shell at all.
+ */
+function quote(value) {
+    return WINDOWS ? `"${value.replace(/"/g, '""')}"` : value;
+}
+function run(binary, args, options = {}) {
+    const common = { stdio: options.stdio, timeout: options.timeout, encoding: 'utf-8' };
+    return WINDOWS
+        ? (0, node_child_process_1.spawnSync)([binary, ...args.map(quote)].join(' '), { ...common, shell: true })
+        : (0, node_child_process_1.spawnSync)(binary, args, common);
+}

package/dist/state.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldNudge = shouldNudge;
+exports.markNudged = markNudged;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const NUDGE_INTERVAL_MS = 24 * 60 * 60 * 1000;
+function statePath() {
+    return (0, node_path_1.join)((0, node_os_1.homedir)(), '.xflow', 'state.json');
+}
+function read() {
+    const path = statePath();
+    if (!(0, node_fs_1.existsSync)(path))
+        return {};
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(path, 'utf-8'));
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Once a day per version. CI never updates the CLI, so it hears nothing. */
+function shouldNudge(version) {
+    if (process.env.CI)
+        return false;
+    const state = read();
+    if (state.nudgedVersion !== version)
+        return true;
+    const at = state.nudgedAt ? Date.parse(state.nudgedAt) : Number.NaN;
+    if (!Number.isFinite(at))
+        return true;
+    return Date.now() - at > NUDGE_INTERVAL_MS;
+}
+/** Best effort: a read-only home folder must not break the command that just worked. */
+function markNudged(version) {
+    try {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.join)((0, node_os_1.homedir)(), '.xflow'), { recursive: true, mode: 0o700 });
+        const state = { ...read(), nudgedVersion: version, nudgedAt: new Date().toISOString() };
+        (0, node_fs_1.writeFileSync)(statePath(), `${JSON.stringify(state, null, 2)}\n`, 'utf-8');
+    }
+    catch {
+        // Worst case the notice repeats next time.
+    }
+}

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

package/package.json

@@ -1,22 +1,22 @@
-{
-  "name": "@getxflow/cli",
-  "version": "0.5.1",
-  "description": "CLI for the XFlow platform: source sync, deployment and publishing of applications",
-  "license": "UNLICENSED",
-  "engines": {
-    "node": ">=20"
-  },
-  "bin": {
-    "xflow": "dist/bin.js"
-  },
-  "files": [
-    "dist",
-    "skills"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@getxflow/cli",
+  "version": "0.6.1",
+  "description": "CLI for the XFlow platform: source sync, deployment and publishing of applications",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "xflow": "dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/xflow/SKILL.md

@@ -17,6 +17,10 @@ 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.
 
+When the CLI says a newer version is out, or refuses to work because the platform wants
+a newer one, run `xflow update`. It also rewrites these instructions, which ship inside
+the package: what you are reading may be older than the platform you are working on.
+
 ## Hard rules
 
 These mistakes cost the most because nothing fails at the moment they are made, or