@mfjjs/ruflo-setup 0.2.5 → 0.2.6

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.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

@@ -16,7 +16,7 @@ Cross-platform npm CLI to bootstrap a project with Ruflo on Windows and Linux.
   <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:
 
@@ -42,9 +42,12 @@ corepack prepare pnpm@latest --activate
 ## 📦 Installation
 
 ```powershell
-pnpm -i -g @mfjjs/ruflo-setup
+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
 
 If you’re working on:
@@ -60,6 +63,20 @@ You only need to do this once in each folder.  Just run the command and you’re
 
 ## 🚀 Usage
 
+### Cleanup
+Remove any previous npm global installs of Ruflo packages that could conflict with the pnpm-managed versions:
+
+```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. It does not touch pnpm globals. Run this before setup if you suspect stale npm globals are shadowing the pnpm-installed binaries.
+
+```bash
+# preview what would be removed without making changes
+ruflo-setup cleanup --dry-run
+```
+
 ### Status
 Check whether all Ruflo feature layers (0–8) are enabled in the current project:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mfjjs/ruflo-setup",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "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 } 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 cleanup [--dry-run]
   ruflo-setup hooks install [options]
   ruflo-setup hooks status
 
@@ -31,9 +32,15 @@ Options:
   --version, -v    Print version and exit
   --verbose        Extra output
 
+Commands:
+  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 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 +100,19 @@ export async function runCli(argv, cwd) {
       return 1;
     }
 
+    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',
@@ -233,3 +276,37 @@ 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.');
+}

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)