@mfjjs/ruflo-setup 0.2.5 → 0.2.7

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 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)
+
+
+### Features
+
+* **cli:** add cleanup command to remove Ruflo packages from npm global registry. 5151c70
+
 ### [0.2.5](///compare/v0.2.4...v0.2.5) (2026-03-17)
 
 ### [0.2.4](https://gitlab.mfj.local:8022/mario/ruflo-setup/compare/v0.2.3...v0.2.4) (2026-03-17)

package/README.md

@@ -11,12 +11,26 @@ 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>
 
 - Node.js 20+
-- pnpm available on PATH
+- pnpm **10.32.1 or higher** available on PATH
 
 Quickest pnpm install by platform:
 
@@ -41,26 +55,50 @@ corepack prepare pnpm@latest --activate
 
 ## 📦 Installation
 
-```powershell
-pnpm -i -g @mfjjs/ruflo-setup
+Install the CLI globally once:
+
+```bash
+pnpm add -g @mfjjs/ruflo-setup
 ```
 
-## 💡 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
+
+# preview what would happen without making any changes
+ruflo-setup --dry-run
+
+# skip the ruflo global install step
+ruflo-setup --skip-init
+
+# skip global hook installation
+ruflo-setup --no-hooks
+
+# 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
@@ -70,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
@@ -78,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
@@ -137,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`
@@ -144,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.5",
+  "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 } 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,8 @@ 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
 
@@ -31,9 +33,17 @@ Options:
   --version, -v    Print version and exit
   --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
   ruflo-setup --dry-run --skip-init
   ruflo-setup hooks status
   ruflo-setup hooks install --dry-run
@@ -93,6 +103,24 @@ 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');
+        const ok = await confirm('Remove Ruflo packages from npm global registry? [y/N] ');
+        if (!ok) {
+          process.stdout.write('Aborted. No changes made.\n');
+          return 0;
+        }
+      }
+      runCleanup({ dryRun: flags.dryRun });
+      return 0;
+    }
+
     await runSetup({
       cwd,
       packageRoot,

package/src/setup.js

@@ -33,30 +33,49 @@ function getPnpmInstallSuggestions(platform) {
   ];
 }
 
+const MIN_PNPM_VERSION = '10.32.1';
+
+function parseSemver(str) {
+  const [major = 0, minor = 0, patch = 0] = str.trim().split('.').map(Number);
+  return { major, minor, patch };
+}
+
+function semverGte(a, b) {
+  if (a.major !== b.major) return a.major > b.major;
+  if (a.minor !== b.minor) return a.minor > b.minor;
+  return a.patch >= b.patch;
+}
+
 function ensurePnpmAvailable() {
   const check = spawnSync('pnpm', ['--version'], {
-    stdio: 'ignore',
+    stdio: ['ignore', 'pipe', 'ignore'],
     shell: process.platform === 'win32'
   });
 
-  if (check.status === 0 && !check.error) {
-    return;
+  if (check.status !== 0 || check.error) {
+    const platformLabel = process.platform === 'win32'
+      ? 'Windows'
+      : process.platform === 'darwin'
+        ? 'macOS'
+        : 'Linux';
+    const suggestions = getPnpmInstallSuggestions(process.platform)
+      .map((command) => `  - ${command}`)
+      .join('\n');
+
+    throw new Error(
+      `pnpm is required but was not found in PATH.\n` +
+      `Install pnpm, then re-run ruflo-setup.\n` +
+      `Quick install options for ${platformLabel}:\n${suggestions}`
+    );
   }
 
-  const platformLabel = process.platform === 'win32'
-    ? 'Windows'
-    : process.platform === 'darwin'
-      ? 'macOS'
-      : 'Linux';
-  const suggestions = getPnpmInstallSuggestions(process.platform)
-    .map((command) => `  - ${command}`)
-    .join('\n');
-
-  throw new Error(
-    `pnpm is required but was not found in PATH.\n` +
-    `Install pnpm, then re-run ruflo-setup.\n` +
-    `Quick install options for ${platformLabel}:\n${suggestions}`
-  );
+  const version = (check.stdout || '').toString().trim();
+  if (!semverGte(parseSemver(version), parseSemver(MIN_PNPM_VERSION))) {
+    throw new Error(
+      `pnpm ${MIN_PNPM_VERSION} or higher is required, but found ${version}.\n` +
+      `Upgrade with: pnpm self-update`
+    );
+  }
 }
 
 function runPnpmInit({ force, cwd, dryRun }) {
@@ -67,22 +86,46 @@ function runPnpmInit({ force, cwd, dryRun }) {
 
   if (dryRun) {
     logLine(`  [DRY RUN] Would run: pnpm add -g ruflo@latest`);
+    logLine(`  [DRY RUN] Would run: pnpm approve-builds -g --all  (if changes detected)`);
     logLine(`  [DRY RUN] Would run: ruflo ${initArgs.join(' ')}`);
     return;
   }
 
   ensurePnpmAvailable();
 
+  // Capture stdout to detect whether pnpm installed/updated anything.
+  // Progress spinners go to stderr (still shown to user); stdout has the summary.
   const install = spawnSync('pnpm', ['add', '-g', 'ruflo@latest'], {
     cwd,
-    stdio: 'inherit',
+    stdio: ['inherit', 'pipe', 'inherit'],
     shell: process.platform === 'win32'
   });
 
+  const installOutput = (install.stdout || '').toString();
+  if (installOutput) {
+    process.stdout.write(installOutput);
+  }
+
   if (install.status !== 0) {
     throw new Error(`pnpm add -g ruflo@latest failed with exit code ${install.status}`);
   }
 
+  // pnpm prints a "Packages:" summary line and "+ pkg version" lines when
+  // something is actually installed or updated. When already up to date the
+  // stdout is empty or contains only "Already up to date".
+  const somethingChanged = /Packages:/i.test(installOutput) || /^\+\s/m.test(installOutput);
+  if (somethingChanged) {
+    logLine('  Changes detected — running pnpm approve-builds -g --all ...');
+    const approve = spawnSync('pnpm', ['approve-builds', '-g', '--all'], {
+      cwd,
+      stdio: 'inherit',
+      shell: process.platform === 'win32'
+    });
+    if (approve.status !== 0) {
+      throw new Error(`pnpm approve-builds -g --all failed with exit code ${approve.status}`);
+    }
+  }
+
   const run = spawnSync('ruflo', initArgs, {
     cwd,
     stdio: 'inherit',
@@ -128,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,
@@ -146,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) {
@@ -233,3 +317,64 @@ export async function runSetup({
   logLine('  2. Run: claude');
   logLine('  3. Verify hooks: ruflo-setup hooks status');
 }
+
+const CLEANUP_NPM_PACKAGES = [
+  'ruflo',
+  '@mfjjs/ruflo-setup',
+  'ruflo-setup',
+  'claude-flow',
+  '@claude-flow/cli',
+  'ruv-swarm'
+];
+
+export function runCleanup({ dryRun = false } = {}) {
+  logLine('');
+  logLine('Ruflo Cleanup — removing from npm global registry');
+  logLine(`Packages: ${CLEANUP_NPM_PACKAGES.join(', ')}`);
+  logLine('');
+
+  if (dryRun) {
+    logLine(`  [DRY RUN] Would run: npm uninstall -g ${CLEANUP_NPM_PACKAGES.join(' ')}`);
+    logLine('');
+    return;
+  }
+
+  const result = spawnSync('npm', ['uninstall', '-g', ...CLEANUP_NPM_PACKAGES], {
+    stdio: 'inherit',
+    shell: process.platform === 'win32'
+  });
+
+  if (result.status !== 0) {
+    throw new Error(`npm uninstall -g failed with exit code ${result.status}`);
+  }
+
+  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) },

package/templates/ruflo-setup.md

@@ -5,7 +5,7 @@ Set up Ruflo + Claude Flow V3 in the current project directory.
 ## Requirements
 
 - Node.js 20+
-- pnpm installed and available on PATH
+- pnpm 10.32.1+ installed and available on PATH
 
 Quickest pnpm install by platform:
 
@@ -41,15 +41,50 @@ Runs `pnpm add -g @mfjjs/ruflo-setup` then `ruflo-setup` which:
 3. Installs a global `SessionStart` hook in `~/.claude/settings.json` that warns when Ruflo is not configured
 4. May refresh `~/.claude/commands/ruflo-setup.md` from the latest packaged template when differences are detected
 
+## Options
+
+### cleanup
+
+Removes all Ruflo-related packages from the **npm** global registry (does not touch pnpm globals).
+
+Packages removed: `ruflo`, `@mfjjs/ruflo-setup`, `ruflo-setup`, `claude-flow`, `@claude-flow/cli`, `ruv-swarm`
+
 ## Instructions for Claude
 
 When the user runs /ruflo-setup:
 
+### Default (no arguments) — install
+
 1. Confirm the current working directory with the user
 2. Check if `.mcp.json` already exists — if so, warn and ask before overwriting
-3. Run the setup CLI:
+3. Check pnpm version is at least 10.32.1:
+   ```bash
+   pnpm --version
+   ```
+   If the version is lower than 10.32.1, stop and tell the user to upgrade pnpm before continuing.
+4. Run the setup CLI and capture output to detect whether pnpm modified anything:
    ```bash
    pnpm add -g @mfjjs/ruflo-setup
+   pnpm add -g ruflo@latest 2>&1 | tee /tmp/ruflo-pnpm-add.log
+   ```
+   After the `pnpm add -g ruflo@latest` step, inspect the output. If pnpm installed or updated any packages (i.e. the output does NOT contain "Already up to date" or an equivalent no-change message), run:
+   ```bash
+   pnpm approve-builds -g --all
+   ```
+   Skip `approve-builds` if nothing changed.
+5. Run the setup tool:
+   ```bash
    ruflo-setup
    ```
-4. Report what was installed and remind the user to restart Claude Code to load the new MCP servers
+6. Report what was installed and remind the user to restart Claude Code to load the new MCP servers
+
+### cleanup
+
+When the user runs `/ruflo-setup cleanup`:
+
+1. Warn the user that this will remove Ruflo packages from the **npm** global registry and ask for confirmation
+2. On confirmation, run:
+   ```bash
+   ruflo-setup cleanup
+   ```
+3. Report which packages were removed and which were not found (not found is fine — it means they were already clean)