@mfjjs/ruflo-setup 0.2.7 → 0.2.8

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.8](///compare/v0.2.7...v0.2.8) (2026-03-31)
+
+
+### Features
+
+* **docs:** add related documentation b67343a
+* **docs:** add RuFlo enabled session notes and usage checklist bd9d96a
+* enhance setup process with .gitignore updates and cross-platform compatibility for .mcp.json 4b44558
+
+
+### Bug Fixes
+
+* update toPlatformMcpConfig to use npx instead of pnpm for cross-platform compatibility e7cf99f
+
 ### [0.2.7](///compare/v0.2.6...v0.2.7) (2026-03-20)
 
 

package/README.md

@@ -74,8 +74,9 @@ ruflo-setup
 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
+3. Write a platform-aware `.mcp.json` (MCP servers use `npx` for cross-platform compatibility)
+4. Add `.mcp.json` and `.claude/settings.json` to the project's `.gitignore`
+5. Install a global Claude Code `SessionStart` hook
 
 Additional options:
 
@@ -152,7 +153,7 @@ ruflo-setup cleanup --dry-run
 - `package.json`: npm metadata, scripts, and `bin` mapping
 - `bin/ruflo-setup.js`: executable entry file the shell runs
 - `src/cli.js`: command router and argument handling
-- `src/setup.js`: setup workflow (`init`, `.mcp.json`, template copy)
+- `src/setup.js`: setup workflow (`init`, `.mcp.json`, `.gitignore`, template copy)
 - `src/status.js`: layer-by-layer feature status checker (Layers 0–8)
 - `src/hooks.js`: global `check-ruflo` hook install/status
 - `src/utils.js`: reusable filesystem and argument helpers
@@ -185,7 +186,8 @@ Flow:
 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`
+	 - writes platform-aware `.mcp.json` (MCP servers invoked via `npx` for cross-platform compatibility)
+	 - adds `.mcp.json` and `.claude/settings.json` to the project's `.gitignore`
 	 - copies `templates/CLAUDE.md`
 	 - installs global SessionStart hook (unless skipped)
 

package/package.json

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

package/src/setup.js

@@ -1,380 +1,414 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import os from 'node:os';
-import { spawnSync } from 'node:child_process';
-import { pathExists, copyFileSync, confirm, toPlatformMcpConfig, writeJson } from './utils.js';
-import { installGlobalCheckRufloHook } from './hooks.js';
-
-function logLine(message) {
-  process.stdout.write(`${message}\n`);
-}
-
-function getPnpmInstallSuggestions(platform) {
-  if (platform === 'win32') {
-    return [
-      'winget install -e --id pnpm.pnpm',
-      'corepack enable && corepack prepare pnpm@latest --activate',
-      'npm install -g pnpm'
-    ];
-  }
-
-  if (platform === 'darwin') {
-    return [
-      'brew install pnpm',
-      'corepack enable && corepack prepare pnpm@latest --activate',
-      'npm install -g pnpm'
-    ];
-  }
-
-  return [
-    'curl -fsSL https://get.pnpm.io/install.sh | sh -',
-    'corepack enable && corepack prepare pnpm@latest --activate',
-    'npm install -g pnpm'
-  ];
-}
-
-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', 'pipe', 'ignore'],
-    shell: process.platform === 'win32'
-  });
-
-  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 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 }) {
-  const initArgs = ['init', '--full'];
-  if (force) {
-    initArgs.push('--force');
-  }
-
-  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', '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',
-    shell: process.platform === 'win32'
-  });
-
-  if (run.status !== 0) {
-    throw new Error(`ruflo init failed with exit code ${run.status}`);
-  }
-}
-
-function writeMcpJson({ cwd, dryRun }) {
-  const mcpPath = path.join(cwd, '.mcp.json');
-  const mcpConfig = toPlatformMcpConfig(process.platform);
-
-  if (dryRun) {
-    const action = pathExists(mcpPath) ? 'overwrite' : 'write';
-    logLine(`  [DRY RUN] Would ${action}: ${mcpPath}`);
-    return;
-  }
-
-  writeJson(mcpPath, mcpConfig);
-  logLine('  .mcp.json written for this platform.');
-}
-
-function syncGlobalCommandTemplate({ packageRoot, dryRun }) {
-  const src = path.join(packageRoot, 'templates', 'ruflo-setup.md');
-  const dest = path.join(os.homedir(), '.claude', 'commands', 'ruflo-setup.md');
-  const exists = pathExists(dest);
-  const operation = exists ? 'update' : 'install';
-  const srcContent = fs.readFileSync(src, 'utf8');
-  const changed = !exists || fs.readFileSync(dest, 'utf8') !== srcContent;
-
-  if (dryRun || !changed) {
-    return { dest, changed, operation };
-  }
-
-  copyFileSync(src, dest);
-  return { dest, changed, operation };
-}
-
-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,
-  force = false,
-  dryRun = false,
-  skipInit = false,
-  noHooks = false,
-  yes = false,
-  verbose = false
-}) {
-  logLine('');
-  logLine('Ruflo Setup (npm CLI)');
-  logLine(`Target directory: ${cwd}`);
-  if (dryRun) {
-    logLine('[DRY RUN - no changes will be made]');
-  }
-  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) {
-    if (dryRun) {
-      logLine(`  [DRY RUN] Would ${preflightCommandResult.operation}: ${preflightCommandResult.dest}`);
-    } else if (preflightCommandResult.operation === 'install') {
-      logLine(`  Installed command template at: ${preflightCommandResult.dest}`);
-    } else {
-      logLine(`  Updated command template at: ${preflightCommandResult.dest}`);
-    }
-  } else {
-    logLine(`  Command template already up to date: ${preflightCommandResult.dest}`);
-  }
-  logLine('');
-
-  if (isAlreadyConfigured(cwd) && !force && !yes) {
-    logLine('WARNING: This project already has Ruflo configuration.');
-    const shouldOverwrite = await confirm('Overwrite existing configuration? [y/N] ');
-    if (!shouldOverwrite) {
-      logLine('Aborted. No changes made.');
-      return;
-    }
-  }
-
-  if (!skipInit) {
-    logLine('Step 1: Running pnpm add -g ruflo@latest && ruflo init --full ...');
-    runPnpmInit({ force, cwd, dryRun });
-    if (!dryRun) {
-      logLine('  ruflo init completed.');
-    }
-    logLine('');
-  } else {
-    logLine('Step 1: Skipped ruflo init (--skip-init).');
-    logLine('');
-  }
-
-  logLine('Step 2: Writing platform-aware .mcp.json ...');
-  writeMcpJson({ cwd, dryRun });
-  logLine('');
-
-  if (!noHooks) {
-    logLine('Step 3: Installing global SessionStart check-ruflo hook ...');
-    const hookResult = installGlobalCheckRufloHook({ packageRoot, dryRun });
-    if (hookResult.inserted) {
-      logLine(`  Hook installed in: ${hookResult.settingsPath}`);
-    } else {
-      logLine(`  Hook already present in: ${hookResult.settingsPath}`);
-    }
-    if (verbose) {
-      logLine(`  Hook command: ${hookResult.hookCommand}`);
-    }
-    logLine('');
-  } else {
-    logLine('Step 3: Skipped hook installation (--no-hooks).');
-    logLine('');
-  }
-
-  logLine('Step 4: Installing global /ruflo-setup command ...');
-  if (dryRun) {
-    if (preflightCommandResult.changed) {
-      logLine(`  [DRY RUN] Would ${preflightCommandResult.operation}: ${preflightCommandResult.dest}`);
-    } else {
-      logLine(`  [DRY RUN] Command already up to date: ${preflightCommandResult.dest}`);
-    }
-  } else if (preflightCommandResult.changed) {
-    if (preflightCommandResult.operation === 'install') {
-      logLine(`  Command installed at: ${preflightCommandResult.dest}`);
-    } else {
-      logLine(`  Command updated at: ${preflightCommandResult.dest}`);
-    }
-  } else {
-    logLine(`  Command already up to date: ${preflightCommandResult.dest}`);
-  }
-  logLine('');
-
-  if (dryRun) {
-    logLine('Dry run complete. No changes were made.');
-    return;
-  }
-
-  logLine('Setup complete!');
-  logLine('');
-  logLine('Next steps:');
-  logLine('  1. Edit CLAUDE.md for project-specific Build & Test commands');
-  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.');
-}
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { pathExists, copyFileSync, confirm, toPlatformMcpConfig, writeJson } from './utils.js';
+import { installGlobalCheckRufloHook } from './hooks.js';
+
+function logLine(message) {
+  process.stdout.write(`${message}\n`);
+}
+
+function getPnpmInstallSuggestions(platform) {
+  if (platform === 'win32') {
+    return [
+      'winget install -e --id pnpm.pnpm',
+      'corepack enable && corepack prepare pnpm@latest --activate',
+      'npm install -g pnpm'
+    ];
+  }
+
+  if (platform === 'darwin') {
+    return [
+      'brew install pnpm',
+      'corepack enable && corepack prepare pnpm@latest --activate',
+      'npm install -g pnpm'
+    ];
+  }
+
+  return [
+    'curl -fsSL https://get.pnpm.io/install.sh | sh -',
+    'corepack enable && corepack prepare pnpm@latest --activate',
+    'npm install -g pnpm'
+  ];
+}
+
+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', 'pipe', 'ignore'],
+    shell: process.platform === 'win32'
+  });
+
+  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 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 }) {
+  const initArgs = ['init', '--full'];
+  if (force) {
+    initArgs.push('--force');
+  }
+
+  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', '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',
+    shell: process.platform === 'win32'
+  });
+
+  if (run.status !== 0) {
+    throw new Error(`ruflo init failed with exit code ${run.status}`);
+  }
+}
+
+function writeMcpJson({ cwd, dryRun }) {
+  const mcpPath = path.join(cwd, '.mcp.json');
+  const mcpConfig = toPlatformMcpConfig(process.platform);
+
+  if (dryRun) {
+    const action = pathExists(mcpPath) ? 'overwrite' : 'write';
+    logLine(`  [DRY RUN] Would ${action}: ${mcpPath}`);
+    return;
+  }
+
+  writeJson(mcpPath, mcpConfig);
+  logLine('  .mcp.json written for this platform.');
+}
+
+function syncGlobalCommandTemplate({ packageRoot, dryRun }) {
+  const src = path.join(packageRoot, 'templates', 'ruflo-setup.md');
+  const dest = path.join(os.homedir(), '.claude', 'commands', 'ruflo-setup.md');
+  const exists = pathExists(dest);
+  const operation = exists ? 'update' : 'install';
+  const srcContent = fs.readFileSync(src, 'utf8');
+  const changed = !exists || fs.readFileSync(dest, 'utf8') !== srcContent;
+
+  if (dryRun || !changed) {
+    return { dest, changed, operation };
+  }
+
+  copyFileSync(src, dest);
+  return { dest, changed, operation };
+}
+
+function updateGitignore({ cwd, dryRun }) {
+  const gitignorePath = path.join(cwd, '.gitignore');
+  const entries = ['.mcp.json', '.claude/settings.json'];
+
+  if (dryRun) {
+    logLine(`  [DRY RUN] Would ensure ${gitignorePath} contains: ${entries.join(', ')}`);
+    return;
+  }
+
+  let content = pathExists(gitignorePath) ? fs.readFileSync(gitignorePath, 'utf8') : '';
+  const lines = content.split('\n');
+  const added = [];
+
+  for (const entry of entries) {
+    if (!lines.some((line) => line.trim() === entry)) {
+      added.push(entry);
+    }
+  }
+
+  if (added.length === 0) {
+    logLine(`  .gitignore already contains required entries.`);
+    return;
+  }
+
+  const suffix = content.length > 0 && !content.endsWith('\n') ? '\n' : '';
+  content = content + suffix + added.join('\n') + '\n';
+  fs.writeFileSync(gitignorePath, content, 'utf8');
+  logLine(`  Added to .gitignore: ${added.join(', ')}`);
+}
+
+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,
+  force = false,
+  dryRun = false,
+  skipInit = false,
+  noHooks = false,
+  yes = false,
+  verbose = false
+}) {
+  logLine('');
+  logLine('Ruflo Setup (npm CLI)');
+  logLine(`Target directory: ${cwd}`);
+  if (dryRun) {
+    logLine('[DRY RUN - no changes will be made]');
+  }
+  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) {
+    if (dryRun) {
+      logLine(`  [DRY RUN] Would ${preflightCommandResult.operation}: ${preflightCommandResult.dest}`);
+    } else if (preflightCommandResult.operation === 'install') {
+      logLine(`  Installed command template at: ${preflightCommandResult.dest}`);
+    } else {
+      logLine(`  Updated command template at: ${preflightCommandResult.dest}`);
+    }
+  } else {
+    logLine(`  Command template already up to date: ${preflightCommandResult.dest}`);
+  }
+  logLine('');
+
+  if (isAlreadyConfigured(cwd) && !force && !yes) {
+    logLine('WARNING: This project already has Ruflo configuration.');
+    const shouldOverwrite = await confirm('Overwrite existing configuration? [y/N] ');
+    if (!shouldOverwrite) {
+      logLine('Aborted. No changes made.');
+      return;
+    }
+  }
+
+  if (!skipInit) {
+    logLine('Step 1: Running pnpm add -g ruflo@latest && ruflo init --full ...');
+    runPnpmInit({ force, cwd, dryRun });
+    if (!dryRun) {
+      logLine('  ruflo init completed.');
+    }
+    logLine('');
+  } else {
+    logLine('Step 1: Skipped ruflo init (--skip-init).');
+    logLine('');
+  }
+
+  logLine('Step 2: Writing platform-aware .mcp.json ...');
+  writeMcpJson({ cwd, dryRun });
+  logLine('');
+
+  logLine('Step 3: Updating .gitignore ...');
+  updateGitignore({ cwd, dryRun });
+  logLine('');
+
+  if (!noHooks) {
+    logLine('Step 4: Installing global SessionStart check-ruflo hook ...');
+    const hookResult = installGlobalCheckRufloHook({ packageRoot, dryRun });
+    if (hookResult.inserted) {
+      logLine(`  Hook installed in: ${hookResult.settingsPath}`);
+    } else {
+      logLine(`  Hook already present in: ${hookResult.settingsPath}`);
+    }
+    if (verbose) {
+      logLine(`  Hook command: ${hookResult.hookCommand}`);
+    }
+    logLine('');
+  } else {
+    logLine('Step 4: Skipped hook installation (--no-hooks).');
+    logLine('');
+  }
+
+  logLine('Step 5: Installing global /ruflo-setup command ...');
+  if (dryRun) {
+    if (preflightCommandResult.changed) {
+      logLine(`  [DRY RUN] Would ${preflightCommandResult.operation}: ${preflightCommandResult.dest}`);
+    } else {
+      logLine(`  [DRY RUN] Command already up to date: ${preflightCommandResult.dest}`);
+    }
+  } else if (preflightCommandResult.changed) {
+    if (preflightCommandResult.operation === 'install') {
+      logLine(`  Command installed at: ${preflightCommandResult.dest}`);
+    } else {
+      logLine(`  Command updated at: ${preflightCommandResult.dest}`);
+    }
+  } else {
+    logLine(`  Command already up to date: ${preflightCommandResult.dest}`);
+  }
+  logLine('');
+
+  if (dryRun) {
+    logLine('Dry run complete. No changes were made.');
+    return;
+  }
+
+  logLine('Setup complete!');
+  logLine('');
+  logLine('Next steps:');
+  logLine('  1. Edit CLAUDE.md for project-specific Build & Test commands');
+  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/utils.js

@@ -1,120 +1,120 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import readline from 'node:readline';
-
-export function pathExists(filePath) {
-  return fs.existsSync(filePath);
-}
-
-export function readJsonSafe(filePath, fallbackValue = {}) {
-  if (!pathExists(filePath)) {
-    return fallbackValue;
-  }
-  try {
-    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
-  } catch {
-    return fallbackValue;
-  }
-}
-
-export function writeJson(filePath, value) {
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
-}
-
-export function copyFileSync(src, dest) {
-  fs.mkdirSync(path.dirname(dest), { recursive: true });
-  fs.copyFileSync(src, dest);
-}
-
-export async function confirm(question) {
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout
-  });
-
-  const answer = await new Promise((resolve) => {
-    rl.question(question, resolve);
-  });
-
-  rl.close();
-  return /^[Yy]$/.test((answer || '').trim());
-}
-
-export function parseArgs(argv) {
-  const flags = {
-    force: false,
-    dryRun: false,
-    yes: false,
-    noHooks: false,
-    skipInit: false,
-    verbose: false,
-    command: 'setup'
-  };
-
-  const positional = [];
-  for (const item of argv) {
-    if (item === '--force' || item === '-f') flags.force = true;
-    else if (item === '--dry-run') flags.dryRun = true;
-    else if (item === '--yes' || item === '-y') flags.yes = true;
-    else if (item === '--no-hooks') flags.noHooks = true;
-    else if (item === '--skip-init') flags.skipInit = true;
-    else if (item === '--verbose') flags.verbose = true;
-    else positional.push(item);
-  }
-
-  if (positional.length > 0) {
-    flags.command = positional[0];
-  }
-
-  return flags;
-}
-
-export function toPlatformMcpConfig(platform) {
-  const isWindows = platform === 'win32';
-  const command = isWindows ? 'cmd' : 'pnpm';
-  const pnpmArgs = isWindows ? ['/c', 'pnpm', 'dlx'] : ['dlx'];
-
-  const makeArgs = (pkg, extraArgs) => {
-    return [...pnpmArgs, pkg, ...extraArgs];
-  };
-
-  return {
-    mcpServers: {
-      'claude-flow': {
-        command,
-        args: makeArgs('@claude-flow/cli@latest', ['mcp', 'start']),
-        env: {
-          npm_config_update_notifier: 'false',
-          CLAUDE_FLOW_MODE: 'v3',
-          CLAUDE_FLOW_HOOKS_ENABLED: 'true',
-          CLAUDE_FLOW_TOPOLOGY: 'hierarchical-mesh',
-          CLAUDE_FLOW_MAX_AGENTS: '15',
-          CLAUDE_FLOW_MEMORY_BACKEND: 'hybrid',
-          MCP_GROUP_SECURITY: 'true',
-          MCP_GROUP_BROWSER: 'true',
-          MCP_GROUP_NEURAL: 'true',
-          MCP_GROUP_AGENTIC_FLOW: 'true'
-        },
-        autoStart: false
-      },
-      'ruv-swarm': {
-        command,
-        args: makeArgs('ruv-swarm', ['mcp', 'start']),
-        env: {
-          npm_config_update_notifier: 'false'
-        },
-        optional: true
-      },
-      'flow-nexus': {
-        command,
-        args: makeArgs('flow-nexus@latest', ['mcp', 'start']),
-        env: {
-          npm_config_update_notifier: 'false'
-        },
-        optional: true,
-        requiresAuth: true
-      }
-    }
-  };
-}
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+
+export function pathExists(filePath) {
+  return fs.existsSync(filePath);
+}
+
+export function readJsonSafe(filePath, fallbackValue = {}) {
+  if (!pathExists(filePath)) {
+    return fallbackValue;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return fallbackValue;
+  }
+}
+
+export function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+export function copyFileSync(src, dest) {
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+}
+
+export async function confirm(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  const answer = await new Promise((resolve) => {
+    rl.question(question, resolve);
+  });
+
+  rl.close();
+  return /^[Yy]$/.test((answer || '').trim());
+}
+
+export function parseArgs(argv) {
+  const flags = {
+    force: false,
+    dryRun: false,
+    yes: false,
+    noHooks: false,
+    skipInit: false,
+    verbose: false,
+    command: 'setup'
+  };
+
+  const positional = [];
+  for (const item of argv) {
+    if (item === '--force' || item === '-f') flags.force = true;
+    else if (item === '--dry-run') flags.dryRun = true;
+    else if (item === '--yes' || item === '-y') flags.yes = true;
+    else if (item === '--no-hooks') flags.noHooks = true;
+    else if (item === '--skip-init') flags.skipInit = true;
+    else if (item === '--verbose') flags.verbose = true;
+    else positional.push(item);
+  }
+
+  if (positional.length > 0) {
+    flags.command = positional[0];
+  }
+
+  return flags;
+}
+
+export function toPlatformMcpConfig(platform) {
+  const isWindows = platform === 'win32';
+  const command = isWindows ? 'cmd' : 'npx';
+  const npxArgs = isWindows ? ['/c', 'npx', '-y'] : ['-y'];
+
+  const makeArgs = (pkg, extraArgs) => {
+    return [...npxArgs, pkg, ...extraArgs];
+  };
+
+  return {
+    mcpServers: {
+      'claude-flow': {
+        command,
+        args: makeArgs('@claude-flow/cli@latest', ['mcp', 'start']),
+        env: {
+          npm_config_update_notifier: 'false',
+          CLAUDE_FLOW_MODE: 'v3',
+          CLAUDE_FLOW_HOOKS_ENABLED: 'true',
+          CLAUDE_FLOW_TOPOLOGY: 'hierarchical-mesh',
+          CLAUDE_FLOW_MAX_AGENTS: '15',
+          CLAUDE_FLOW_MEMORY_BACKEND: 'hybrid',
+          MCP_GROUP_SECURITY: 'true',
+          MCP_GROUP_BROWSER: 'true',
+          MCP_GROUP_NEURAL: 'true',
+          MCP_GROUP_AGENTIC_FLOW: 'true'
+        },
+        autoStart: false
+      },
+      'ruv-swarm': {
+        command,
+        args: makeArgs('ruv-swarm', ['mcp', 'start']),
+        env: {
+          npm_config_update_notifier: 'false'
+        },
+        optional: true
+      },
+      'flow-nexus': {
+        command,
+        args: makeArgs('flow-nexus@latest', ['mcp', 'start']),
+        env: {
+          npm_config_update_notifier: 'false'
+        },
+        optional: true,
+        requiresAuth: true
+      }
+    }
+  };
+}

package/templates/ruflo-setup.md

@@ -1,90 +1,92 @@
-# /ruflo-setup
-
-Set up Ruflo + Claude Flow V3 in the current project directory.
-
-## Requirements
-
-- Node.js 20+
-- pnpm 10.32.1+ installed and available on PATH
-
-Quickest pnpm install by platform:
-
-```bash
-# Windows (recommended)
-winget install -e --id pnpm.pnpm
-
-# macOS (recommended)
-brew install pnpm
-
-# Linux (recommended)
-curl -fsSL https://get.pnpm.io/install.sh | sh -
-```
-
-Alternative (all platforms with recent Node.js):
-
-```bash
-corepack enable
-corepack prepare pnpm@latest --activate
-```
-
-## What this does
-
-Runs `pnpm add -g @mfjjs/ruflo-setup` then `ruflo-setup` which:
-
-1. Runs `pnpm add -g ruflo@latest` then `ruflo init --full` to install:
-   - `.claude/settings.json` with hooks, permissions, and Claude Flow config
-   - `.claude/helpers/` — hook-handler, statusline, auto-memory scripts
-   - `.claude/agents/` — 120+ agent definitions
-   - `.claude/skills/` — 30+ skill definitions
-   - `.claude/commands/` — slash commands
-2. Writes a platform-aware `.mcp.json` (MCP server registration for claude-flow, ruv-swarm, flow-nexus)
-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. 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
-   ```
-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)
+# /ruflo-setup
+
+Set up Ruflo + Claude Flow V3 in the current project directory.
+
+## Requirements
+
+- Node.js 20+
+- pnpm 10.32.1+ installed and available on PATH
+
+Quickest pnpm install by platform:
+
+```bash
+# Windows (recommended)
+winget install -e --id pnpm.pnpm
+
+# macOS (recommended)
+brew install pnpm
+
+# Linux (recommended)
+curl -fsSL https://get.pnpm.io/install.sh | sh -
+```
+
+Alternative (all platforms with recent Node.js):
+
+```bash
+corepack enable
+corepack prepare pnpm@latest --activate
+```
+
+## What this does
+
+Runs `pnpm add -g @mfjjs/ruflo-setup` then `ruflo-setup` which:
+
+1. Runs `pnpm add -g ruflo@latest` then `ruflo init --full` to install:
+   - `.claude/settings.json` with hooks, permissions, and Claude Flow config
+   - `.claude/helpers/` — hook-handler, statusline, auto-memory scripts
+   - `.claude/agents/` — 120+ agent definitions
+   - `.claude/skills/` — 30+ skill definitions
+   - `.claude/commands/` — slash commands
+2. Writes a platform-aware `.mcp.json` (MCP server registration for claude-flow, ruv-swarm, flow-nexus; servers invoked via `npx` for cross-platform compatibility)
+3. Adds `.mcp.json` and `.claude/settings.json` to the project's `.gitignore`
+4. Installs a global `SessionStart` hook in `~/.claude/settings.json` that warns when Ruflo is not configured
+5. 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. 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
+   ```
+6. Ensure `.mcp.json` and `.claude/settings.json` are in the project's `.gitignore` (ruflo-setup does this automatically, but verify if using `--skip-init`)
+7. 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)