@getxflow/cli 0.10.0 → 0.10.2

package/dist/bin.js

@@ -114,7 +114,7 @@ async function run(args) {
                 await (0, env_1.envCheck)();
                 return;
             }
-            if (second === undefined || second === 'list' || second === 'pull') {
+            if (second === undefined || second === 'list') {
                 await (0, env_1.envList)();
                 return;
             }
@@ -216,6 +216,31 @@ function nudge() {
     (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);
 }
+/**
+ * The other staleness, and the one that costs more: the instructions an agent reads are
+ * older than the CLI answering it, and nothing about that is visible in the text. Louder
+ * than the notice above because it is wrong now rather than out of date soon, and it names
+ * the file, because a machine can hold a dozen copies and the wrong one gets edited.
+ *
+ * The command is skills --refresh, not update: what is out of step here is the copies, not
+ * the package, and refreshing needs no network, no npm and no rights on a global folder.
+ * The re-read is half the repair, so it is in the same breath as the command.
+ */
+function nudgeSkill() {
+    const stale = (0, skills_1.staleSkillCopy)(process.cwd());
+    if (stale === null) {
+        // Everything matches, so the day-long silence has nothing left to protect: drop it,
+        // and a copy that drifts after a repair is news again instead of yesterday's answer.
+        (0, state_1.clearSkillNudges)();
+        return;
+    }
+    const key = `${stale} ${version_1.CLI_VERSION}`;
+    if (!(0, state_1.shouldNudgeSkill)(key))
+        return;
+    (0, ui_1.warn)(`${stale} is older than this CLI`);
+    (0, ui_1.note)((0, ui_1.dim)('  Run xflow skills --refresh, then read that file again: the refresh only writes it to disk'));
+    (0, state_1.markSkillNudged)(key);
+}
 async function main() {
     const args = (0, args_1.parseArgs)(process.argv.slice(2));
     if ((0, args_1.flagBool)(args, 'version')) {
@@ -261,6 +286,10 @@ async function main() {
     finally {
         if (!quiet)
             nudge();
+        // Not behind the same flag: a copy out of step with the running package stays wrong
+        // whatever the command was, and when the package itself is the problem the copies
+        // match it and this says nothing anyway.
+        nudgeSkill();
     }
 }
 main().then((code) => {

package/dist/commands/skills.js

@@ -1,5 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.replacePointer = replacePointer;
+exports.copyIsStale = copyIsStale;
+exports.staleSkillCopy = staleSkillCopy;
 exports.installSkillQuietly = installSkillQuietly;
 exports.skills = skills;
 const node_fs_1 = require("node:fs");
@@ -8,6 +11,7 @@ const node_path_1 = require("node:path");
 const args_1 = require("../args");
 const errors_1 = require("../errors");
 const prompt_1 = require("../prompt");
+const update_1 = require("./update");
 const ui_1 = require("../ui");
 const AGENTS = [
     { id: 'claude', label: 'Claude Code', project: ['.claude', 'skills'], global: ['.claude', 'skills'] },
@@ -32,7 +36,8 @@ const POINTER = `${POINTER_MARKER}
 This project is hosted on the XFlow platform and ships through the \`xflow\` CLI, not
 through a git push. Read \`.agents/skills/xflow/SKILL.md\` before deploying, publishing,
 rolling back, touching the database or migrations, cloud functions, schedules,
-environment variables or production logs. Command list: \`xflow help\`.
+environment variables, file storage and uploads, connected accounts or production logs.
+Command list: \`xflow help\`.
 `;
 /** The skill ships inside the package, next to dist. */
 function skillSource() {
@@ -63,13 +68,43 @@ function writeIfChanged(path, content) {
     (0, node_fs_1.writeFileSync)(path, content, 'utf-8');
     return before === null ? 'new' : 'updated';
 }
-/** Append once, by marker: the file belongs to the user. */
-function appendPointer(base) {
+/**
+ * Our own block put back in place, or null when the file has none.
+ *
+ * The block runs from the marker to the next heading of the same level, so whatever the
+ * user wrote around it survives. Appending once was enough while the text never changed;
+ * it does change, and a pointer that names half the sections is worse than an old CLI:
+ * the agent reads it every time, unlike the skill, which at least announces its own age.
+ */
+function replacePointer(text) {
+    const start = text.indexOf(POINTER_MARKER);
+    if (start < 0)
+        return null;
+    // Past our own heading: the newline before it sits at start + length, so the search
+    // begins after it and the first hit is somebody else's section.
+    const after = text.indexOf('\n## ', start + POINTER_MARKER.length + 1);
+    const tail = after < 0 ? '' : `\n${text.slice(after + 1)}`;
+    return `${text.slice(0, start)}${POINTER}${tail}`;
+}
+/** The file belongs to the user: created only on install, rewritten only where ours is. */
+function writePointer(base, create) {
     const path = (0, node_path_1.join)(base, 'AGENTS.md');
     const before = (0, node_fs_1.existsSync)(path) ? (0, node_fs_1.readFileSync)(path, 'utf-8') : null;
-    if (before?.includes(POINTER_MARKER))
+    let next;
+    if (before === null) {
+        if (!create)
+            return null;
+        next = POINTER;
+    }
+    else {
+        const replaced = replacePointer(before);
+        if (replaced === null && !create)
+            return null;
+        next = replaced ?? `${before.replace(/\s*$/, '')}\n\n${POINTER}`;
+    }
+    if (before === next)
         return null;
-    (0, node_fs_1.writeFileSync)(path, before ? `${before.replace(/\s*$/, '')}\n\n${POINTER}` : POINTER, 'utf-8');
+    (0, node_fs_1.writeFileSync)(path, next, 'utf-8');
     return { path, state: before === null ? 'new' : 'updated' };
 }
 function install(base, ids, global) {
@@ -93,12 +128,88 @@ function install(base, ids, global) {
     }
     // Project-level only: these have no global equivalents.
     if (!global) {
-        const pointer = appendPointer(base);
+        const pointer = writePointer(base, true);
         if (pointer)
             changes.push(pointer);
     }
     return changes;
 }
+/**
+ * Every place a copy can live, deduplicated, project copies first. Two consumers read
+ * this list: the refresh below and the staleness check the nudge runs, and they have to
+ * agree on what a copy is, or one of them would report the other's work as undone.
+ *
+ * The Cursor rule is not one of the agent paths and not a plain copy either: it carries
+ * the same body under its own header, hence the flag rather than a second list.
+ */
+function copyPaths(base) {
+    const paths = [];
+    const seen = new Set();
+    const add = (path, rule) => {
+        if (seen.has(path))
+            return;
+        seen.add(path);
+        paths.push({ path, rule });
+    };
+    for (const agent of AGENTS)
+        add(skillPath(base, agent, false), false);
+    add((0, node_path_1.join)(base, ...CURSOR_RULE), true);
+    // A source checkout holds the skill as it is being written, not as it was published,
+    // while the home copies are read from every project on this machine. Refreshing them
+    // from here would hand a draft to every agent on the machine, and reporting them stale
+    // would nag for ever with a command we do not want run. So from a checkout the CLI
+    // minds this folder and nothing else, and both consumers of the list agree because it
+    // is decided here rather than twice.
+    if ((0, update_1.classifyPath)(__dirname) !== 'checkout') {
+        for (const agent of AGENTS)
+            add(skillPath(base, agent, true), false);
+    }
+    return paths;
+}
+/**
+ * The stamp names the CLI version, so it moves on every release even when not a word of
+ * the instructions changed. Comparing it would call every copy on the machine stale after
+ * such a release, which is exactly what comparing content instead of versions avoids.
+ */
+const STAMP = /^These instructions ship with xflow CLI .*$/m;
+/**
+ * Line endings are not a difference either. An editor that saved a copy as CRLF would
+ * otherwise leave the machine announcing a stale skill for ever, and the refresh that
+ * "fixes" it would change nothing visible. Same normalisation the template gate uses.
+ */
+function copyIsStale(expected, actual) {
+    return compared(expected) !== compared(actual);
+}
+function compared(text) {
+    return text.replace(/\r\n/g, '\n').replace(STAMP, '');
+}
+/**
+ * The first installed copy whose text is not what this CLI ships, or null when every
+ * copy matches. Compared by content rather than by a version stamp: a release that left
+ * the skill alone must not declare identical copies stale, and copies old enough to
+ * carry no stamp still have to be recognised.
+ *
+ * Never throws: this runs after a command that already succeeded, and an unreadable file
+ * somewhere in a home folder is not a reason to fail it.
+ */
+function staleSkillCopy(base) {
+    try {
+        const present = copyPaths(base).filter((copy) => (0, node_fs_1.existsSync)(copy.path));
+        if (present.length === 0)
+            return null;
+        const skill = skillSource();
+        const rule = cursorRule(skill);
+        for (const copy of present) {
+            const expected = copy.rule ? rule : skill;
+            if (copyIsStale(expected, (0, node_fs_1.readFileSync)(copy.path, 'utf-8')))
+                return copy.path;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * 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
@@ -106,24 +217,20 @@ function install(base, ids, global) {
  */
 function refreshInstalled(base) {
     const skill = skillSource();
+    const rule = cursorRule(skill);
     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);
+    for (const copy of copyPaths(base)) {
+        if (!(0, node_fs_1.existsSync)(copy.path))
+            continue;
+        const state = writeIfChanged(copy.path, copy.rule ? rule : skill);
         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));
+            changes.push({ path: copy.path, state });
     }
+    // AGENTS.md is read on every task, unlike the lazily loaded skill, so a stale pointer
+    // there misleads more often than a stale skill. Rewritten, never created.
+    const pointer = writePointer(base, false);
+    if (pointer)
+        changes.push(pointer);
     return changes;
 }
 /** Defaults plus whatever is already installed, so an update run refreshes everything. */

package/dist/commands/update.js

@@ -150,10 +150,12 @@ function update() {
         (0, ui_1.note)((0, ui_1.dim)('  Check what is on disk now: xflow --version'));
         return;
     }
-    if (after === version_1.CLI_VERSION) {
+    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}`);
+    else
+        (0, ui_1.ok)(`xflow ${version_1.CLI_VERSION} → ${after}`);
+    // Also when the version did not move: copies drift on their own, from a global install
+    // made by npm directly or a folder that never saw this command. The refresh writes
+    // nothing where the text already matches, so the quiet case stays quiet.
     refreshSkill(root);
 }