@mfjjs/ruflo-setup 0.2.6 → 0.2.7

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [0.2.7](///compare/v0.2.6...v0.2.7) (2026-03-20)
+
+
+### Features
+
+* **cli:** add update command to upgrade ruflo-setup to the latest version 569bc0b
+
 ### [0.2.6](///compare/v0.2.5...v0.2.6) (2026-03-20)
 
 

package/README.md

@@ -11,6 +11,20 @@ Cross-platform npm CLI to bootstrap a project with Ruflo on Windows and Linux.
 - Package name: `@mfjjs/ruflo-setup`
 - Command name: `ruflo-setup`
 - Platform support: Windows and Linux (plus macOS by default)
+
+## 💡 Why You Need This
+
+If you're working on:
+
+* A brownfield application that never had RuFlow configured, or
+* A brand‑new project that hasn't been set up with RuFlow yet,
+
+…then you currently have to configure RuFlow manually in each project. That means recreating the same structure, wiring, and boilerplate over and over.
+
+`ruflo-setup` eliminates all of that. When you run it inside a project directory, it automatically generates the required RuFlow scaffolding — including all the files that belong in the `.claude/` folder — so every project starts from a clean, consistent baseline.
+
+You only need to do this once per project. Just run the command and you're ready to go.
+
 ## 📋 Requirements
 <details>
   <summary>Click to toggle visibility</summary>
@@ -41,43 +55,50 @@ corepack prepare pnpm@latest --activate
 
 ## 📦 Installation
 
-```powershell
+Install the CLI globally once:
+
+```bash
 pnpm add -g @mfjjs/ruflo-setup
-ruflo-setup cleanup
 ```
 
-> **Why run `cleanup` first?** If you previously installed any Ruflo packages via `npm install -g` (e.g. `ruflo`, `claude-flow`, `ruv-swarm`), those npm-global copies can shadow or conflict with the pnpm-managed versions. `ruflo-setup cleanup` removes them from the npm global registry before setup runs, giving you a clean slate.
-
-## 💡 Why You Need This
+## 🚀 Usage
 
-If you’re working on:
+### Setup
 
-* A brownfield application that never had RuFlow configured, or
-* A brand‑new project that hasn’t been set up with RuFlow yet,
+**First, change to your project directory**, then run:
 
-…then you currently have to configure RuFlow manually in each project. That means recreating the same structure, wiring, and boilerplate over and over.
+```bash
+ruflo-setup
+```
 
-The new  command eliminates all of that. When you run it inside a project, it automatically generates the required RuFlow scaffolding — including all the files that belong in the  folder — so every project starts from a clean, consistent baseline.
+That's it for most users. The command will:
+1. Check for a newer version of itself and offer to update before proceeding
+2. Install `ruflo@latest` globally and run `ruflo init --full` to scaffold your project
+3. Write a platform-aware `.mcp.json`
+4. Install a global Claude Code `SessionStart` hook
 
-You only need to do this once in each folder.  Just run the command and you’re ready to go.
+Additional options:
 
-## 🚀 Usage
+```bash
+# non-interactive (skip all prompts)
+ruflo-setup --yes
 
-### Cleanup
-Remove any previous npm global installs of Ruflo packages that could conflict with the pnpm-managed versions:
+# preview what would happen without making any changes
+ruflo-setup --dry-run
 
-```bash
-ruflo-setup cleanup
-```
+# skip the ruflo global install step
+ruflo-setup --skip-init
 
-This uninstalls `ruflo`, `@mfjjs/ruflo-setup`, `ruflo-setup`, `claude-flow`, `@claude-flow/cli`, and `ruv-swarm` from the **npm** global registry. It does not touch pnpm globals. Run this before setup if you suspect stale npm globals are shadowing the pnpm-installed binaries.
+# skip global hook installation
+ruflo-setup --no-hooks
 
-```bash
-# preview what would be removed without making changes
-ruflo-setup cleanup --dry-run
+# hook operations
+ruflo-setup hooks install
+ruflo-setup hooks status
 ```
 
 ### Status
+
 Check whether all Ruflo feature layers (0–8) are enabled in the current project:
 
 ```bash
@@ -87,7 +108,8 @@ ruflo-setup status
 This prints a layer-by-layer report showing which features are active — prerequisites, global packages, optional WASM/ML packages, MCP servers, tool groups, environment variables, project scaffolding, and the Docker chat UI stack.
 
 ### Bootstrap
-Use this once if you want Claude Code to expose the `/ruflo-setup` command globally.
+
+Use this once if you want Claude Code to expose the `/ruflo-setup` command globally, so you can run it from inside Claude Code chat without using the shell.
 
 ```bash
 ruflo-setup hooks init
@@ -95,27 +117,34 @@ ruflo-setup hooks init
 
 After that, when you open Claude Code in a project that does not already have Ruflo configured, you can run [**/ruflo-setup**](noop:) to start the setup flow.
 
-### Setup
-Use these commands when you want to run the setup directly from a shell.
+### Update
 
-From the target project directory, run one of the following:
+Update `@mfjjs/ruflo-setup` itself to the latest published version:
 
 ```bash
-# full setup
-ruflo-setup
+ruflo-setup update
+```
 
-# non-interactive
-ruflo-setup --yes
+It is best to always have the latest version before running setup. When you run `ruflo-setup` without arguments it automatically checks for a newer version and will prompt you to update if one is found, so in most cases you will not need to run this manually.
 
-# preview only
-ruflo-setup --dry-run --skip-init
+```bash
+# preview without making changes
+ruflo-setup update --dry-run
+```
 
-# skip global hook install
-ruflo-setup --no-hooks
+### Cleanup
 
-# hook operations
-ruflo-setup hooks install
-ruflo-setup hooks status
+If you previously installed any Ruflo packages via `npm install -g`, those npm-global copies can shadow or conflict with the pnpm-managed versions. Run this to remove them and give yourself a clean slate:
+
+```bash
+ruflo-setup cleanup
+```
+
+This uninstalls `ruflo`, `@mfjjs/ruflo-setup`, `ruflo-setup`, `claude-flow`, `@claude-flow/cli`, and `ruv-swarm` from the **npm** global registry only — it does not touch pnpm globals.
+
+```bash
+# preview what would be removed without making changes
+ruflo-setup cleanup --dry-run
 ```
 
 ## 🗂️ Project structure
@@ -154,6 +183,7 @@ Flow:
 3. `bin/ruflo-setup.js` forwards args to `runCli(...)`.
 4. `src/cli.js` parses command and flags.
 5. `src/setup.js` runs setup steps:
+	 - checks for a newer version of itself and prompts to update
 	 - optional `pnpm add -g ruflo@latest` then `ruflo init --full`
 	 - writes platform-aware `.mcp.json`
 	 - copies `templates/CLAUDE.md`
@@ -161,6 +191,10 @@ Flow:
 
 When called as `ruflo-setup status`, step 5 dispatches to `src/status.js` which checks all layers (0–8) and prints a feature status report.
 
+When called as `ruflo-setup update`, it runs `pnpm add -g @mfjjs/ruflo-setup@latest` to update the tool itself.
+
+When called as `ruflo-setup cleanup`, it removes Ruflo packages from the npm global registry to eliminate conflicts with pnpm-managed versions.
+
 ## 🛠️ Local development with pnpm
 
 From this repository root (`setup-ruflo/`):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mfjjs/ruflo-setup",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Cross-platform setup CLI for Ruflo + Claude Flow projects",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -2,7 +2,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
 import { parseArgs } from './utils.js';
-import { runSetup, runCleanup } from './setup.js';
+import { runSetup, runCleanup, runUpdate } from './setup.js';
 import { getGlobalHookStatus, installGlobalCheckRufloHook } from './hooks.js';
 
 const require = createRequire(import.meta.url);
@@ -19,6 +19,7 @@ function printHelp() {
 Usage:
   ruflo-setup [options]
   ruflo-setup status
+  ruflo-setup update [--dry-run]
   ruflo-setup cleanup [--dry-run]
   ruflo-setup hooks install [options]
   ruflo-setup hooks status
@@ -33,11 +34,13 @@ Options:
   --verbose        Extra output
 
 Commands:
+  update           Update @mfjjs/ruflo-setup itself to the latest published version
   cleanup          Remove all Ruflo packages from the npm global registry
                    (ruflo, @mfjjs/ruflo-setup, claude-flow, @claude-flow/cli, ruv-swarm)
 
 Examples:
   ruflo-setup
+  ruflo-setup update
   ruflo-setup status
   ruflo-setup cleanup
   ruflo-setup cleanup --dry-run
@@ -100,6 +103,11 @@ export async function runCli(argv, cwd) {
       return 1;
     }
 
+    if (flags.command === 'update') {
+      runUpdate({ dryRun: flags.dryRun });
+      return 0;
+    }
+
     if (flags.command === 'cleanup') {
       if (!flags.dryRun && !flags.yes) {
         const { confirm } = await import('./utils.js');

package/src/setup.js

@@ -171,6 +171,29 @@ function isAlreadyConfigured(cwd) {
   return pathExists(path.join(cwd, '.mcp.json')) || pathExists(path.join(cwd, '.claude', 'settings.json'));
 }
 
+function getCurrentVersion(packageRoot) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+    return pkg.version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+function getLatestVersion() {
+  try {
+    const result = spawnSync('pnpm', ['view', '@mfjjs/ruflo-setup', 'version'], {
+      stdio: ['ignore', 'pipe', 'ignore'],
+      shell: process.platform === 'win32',
+      timeout: 8000
+    });
+    if (result.status !== 0 || result.error) return null;
+    return (result.stdout || '').toString().trim() || null;
+  } catch {
+    return null;
+  }
+}
+
 export async function runSetup({
   cwd,
   packageRoot,
@@ -189,6 +212,24 @@ export async function runSetup({
   }
   logLine('');
 
+  // Check if a newer version of ruflo-setup itself is available.
+  if (!dryRun && !yes) {
+    const currentVersion = getCurrentVersion(packageRoot);
+    const latestVersion = getLatestVersion();
+    if (latestVersion && !semverGte(parseSemver(currentVersion), parseSemver(latestVersion))) {
+      logLine(`A newer version of ruflo-setup is available: ${latestVersion} (you have ${currentVersion}).`);
+      logLine('It is best to always have the latest version before running setup.');
+      const doUpdate = await confirm('Update @mfjjs/ruflo-setup now? [y/N] ');
+      if (doUpdate) {
+        runUpdate({ dryRun: false });
+        logLine('');
+        logLine('Please re-run ruflo-setup to continue with the updated version.');
+        return;
+      }
+      logLine('');
+    }
+  }
+
   logLine('Preflight: Syncing global /ruflo-setup command template ...');
   const preflightCommandResult = syncGlobalCommandTemplate({ packageRoot, dryRun });
   if (preflightCommandResult.changed) {
@@ -310,3 +351,30 @@ export function runCleanup({ dryRun = false } = {}) {
   logLine('');
   logLine('Cleanup complete.');
 }
+
+export function runUpdate({ dryRun = false } = {}) {
+  logLine('');
+  logLine('Ruflo Setup Update');
+  logLine('');
+
+  if (dryRun) {
+    logLine('[DRY RUN] Would run: pnpm add -g @mfjjs/ruflo-setup@latest');
+    logLine('');
+    return;
+  }
+
+  ensurePnpmAvailable();
+
+  logLine('Updating @mfjjs/ruflo-setup to latest...');
+  const result = spawnSync('pnpm', ['add', '-g', '@mfjjs/ruflo-setup@latest'], {
+    stdio: 'inherit',
+    shell: process.platform === 'win32'
+  });
+
+  if (result.status !== 0) {
+    throw new Error(`pnpm add -g @mfjjs/ruflo-setup@latest failed with exit code ${result.status}`);
+  }
+
+  logLine('');
+  logLine('Update complete. Re-run ruflo-setup to continue with the updated version.');
+}

package/src/status.js

@@ -40,12 +40,11 @@ function fileExists(p) {
   }
 }
 
-// Flatten npm/pnpm --json list result into a name->version map (1 level deep).
+// Flatten pnpm --json list result into a name->version map (1 level deep).
 function buildPkgMap(jsonText) {
   const map = {};
   try {
     const parsed = JSON.parse(jsonText || '{}');
-    // npm list -g returns an array with one element, pnpm returns an object
     const root = Array.isArray(parsed) ? parsed[0] : parsed;
     const deps = root?.dependencies ?? {};
     for (const [name, info] of Object.entries(deps)) {
@@ -60,13 +59,7 @@ function buildPkgMap(jsonText) {
   return map;
 }
 
-// Tries npm list -g first, falls back to pnpm list -g.
 function getGlobalPkgMap() {
-  const npmRes = spawn('npm', ['list', '-g', '--depth=1', '--json']);
-  if (npmRes.status === 0 && npmRes.stdout) {
-    const m = buildPkgMap(npmRes.stdout);
-    if (Object.keys(m).length > 0) return m;
-  }
   const pnpmRes = spawn('pnpm', ['list', '-g', '--depth=1', '--json']);
   if (pnpmRes.status === 0 && pnpmRes.stdout) {
     return buildPkgMap(pnpmRes.stdout);
@@ -95,7 +88,7 @@ function checkLayer0() {
     const ver = (claudeRes.stdout || '').trim();
     lines.push(`  ${OK} Claude Code CLI${ver ? `  ${ver}` : ''}`); ok += 1;
   } else {
-    lines.push(`  ${MISS} Claude Code CLI  (install: npm install -g @anthropic-ai/claude-code)`);
+    lines.push(`  ${MISS} Claude Code CLI  (install: pnpm add -g @anthropic-ai/claude-code)`);
   }
 
   if (process.env.ANTHROPIC_API_KEY) {
@@ -113,7 +106,7 @@ function checkLayer1(pkgMap) {
   for (const name of ['ruflo', '@mfjjs/ruflo-setup']) {
     const ver = pkgMap[name];
     if (ver) { lines.push(`  ${OK} ${name}${typeof ver === 'string' ? `@${ver}` : ''}`); ok += 1; }
-    else { lines.push(`  ${MISS} ${name}  (install: npm install -g ${name})`); }
+    else { lines.push(`  ${MISS} ${name}  (install: pnpm add -g ${name})`); }
   }
   return { lines, ok, total: 2 };
 }
@@ -268,7 +261,7 @@ export async function runStatus({ cwd, packageRoot }) {
 
     const layers = [
       { title: 'Layer 0: Prerequisites', result: checkLayer0() },
-      { title: 'Layer 1: Global npm Packages', result: checkLayer1(pkgMap) },
+      { title: 'Layer 1: Global Packages', result: checkLayer1(pkgMap) },
       { title: 'Layer 2: Optional Packages (WASM/ML)  — enables AI features', result: checkLayer2(pkgMap) },
       { title: 'Layer 3: MCP Servers (.mcp.json)', result: checkLayer3(mcpJson) },
       { title: 'Layer 4: MCP Tool Groups', result: checkLayer4(mcpJson) },