@mfjjs/ruflo-setup 0.1.8 → 0.2.1

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 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.1](https://gitlab.mfj.local:8022/mario/ruflo-setup/compare/v0.2.0...v0.2.1) (2026-03-14)
+
+
+### Features
+
+* **docs:** update usage section by moving status command first ([e98f473](https://gitlab.mfj.local:8022/mario/ruflo-setup/commit/e98f473f25f53031d8cf08cf8d6bd3bfedcae949))
+
+## [0.2.0](https://gitlab.mfj.local:8022/mario/ruflo-setup/compare/v0.1.9...v0.2.0) (2026-03-14)
+
+
+### ⚠ BREAKING CHANGES
+
+* **cli:** The CLI now includes a new command which may affect existing scripts that rely on the previous command structure.
+
+### Features
+
+* **cli:** add 'status' command to check feature status ([d551664](https://gitlab.mfj.local:8022/mario/ruflo-setup/commit/d551664619635e7efbbc9a9810266ecfe2212d1c))
+* **docs:** add detailed agents and skills sections to Ruflo benefit documentation ([c66d212](https://gitlab.mfj.local:8022/mario/ruflo-setup/commit/c66d212f4ee25390ab139e43131ecb548b7bcb5c))
+* **docs:** add link to ruflo-benefits.md and renamed to plural ([2820aeb](https://gitlab.mfj.local:8022/mario/ruflo-setup/commit/2820aeb5cebbfad0ac7b568291aa55a49076c6c3))
+* **docs:** update Ruflo benefit documentation with agents and skills sections ([8feb883](https://gitlab.mfj.local:8022/mario/ruflo-setup/commit/8feb8836c88ec5096a907eb4c842b0b3b4c55b4c))
+* **status:** enhance directory checks to display count of agents and skills ([3ade22b](https://gitlab.mfj.local:8022/mario/ruflo-setup/commit/3ade22b10ba1840f405b8f239f2a723f6d4089d7))
+
+### [0.1.9](https://gitlab.mfj.local:8022/mario/ruflo-setup/compare/v0.1.8...v0.1.9) (2026-03-13)
+
 ### [0.1.8](https://gitlab.mfj.local:8022/mario/ruflo-setup/compare/v0.1.7...v0.1.8) (2026-03-13)
 
 ### [0.1.7](https://gitlab.mfj.local:8022/mario/ruflo-setup/compare/v0.1.6...v0.1.7) (2026-03-13)

package/README.md

@@ -2,14 +2,16 @@
 
 Cross-platform npm CLI to bootstrap a project with Ruflo on Windows and Linux.
 
-## What this project is
+> **Deep dive:** [`docs/ruflo-benefits.md`](docs/ruflo-benefits.md) is a comprehensive reference (~900 lines) covering every feature layer, the MinCut/RuVector/RVF internals, all 80+ agents, 33 skills, 65 slash commands, and how agents and skills are invoked. Not a quick read.
+
+## 📘 What this project is
 
 `@mfjjs/ruflo-setup` implements the setup with a Node-based CLI command:
 
 - Package name: `@mfjjs/ruflo-setup`
 - Command name: `ruflo-setup`
 - Platform support: Windows and Linux (plus macOS by default)
-## Requirements
+## 📋 Requirements
 <details>
   <summary>Click to toggle visibility</summary>
 
@@ -37,13 +39,35 @@ corepack prepare pnpm@latest --activate
 ```
 </details>
 
-## Installation
+## 📦 Installation
 
 ```powershell
 pnpm -i -g @mfjjs/ruflo-setup
 ```
 
-## Usage
+## 💡 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.
+
+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.
+
+You only need to do this once in each folder.  Just run the command and you’re ready to go.
+
+## 🚀 Usage
+
+### Status
+Check whether all Ruflo feature layers (0–8) are enabled in the current project:
+
+```bash
+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.
@@ -77,19 +101,20 @@ ruflo-setup hooks install
 ruflo-setup hooks status
 ```
 
-## Project structure
+## 🗂️ Project structure
 
 - `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/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
 - `templates/CLAUDE.md`: bundled template copied into target project
 - `claude-hooks/check-ruflo.cjs`: SessionStart hook payload
 - `tests/cli.test.mjs`: smoke tests for CLI behavior
 
-## What the command line calls
+## 🖥️ What the command line calls
 
 After install/link, `ruflo-setup` resolves to your package `bin` entry:
 
@@ -103,7 +128,7 @@ After install/link, `ruflo-setup` resolves to your package `bin` entry:
 
 The shell shim launches `bin/ruflo-setup.js`, which imports `src/cli.js`, which dispatches to setup or hook subcommands.
 
-## How the CLI entry point works
+## ⚙️ How the CLI entry point works
 
 Flow:
 
@@ -117,7 +142,9 @@ Flow:
 	 - copies `templates/CLAUDE.md`
 	 - installs global SessionStart hook (unless skipped)
 
-## Local development with pnpm
+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.
+
+## 🛠️ Local development with pnpm
 
 From this repository root (`setup-ruflo/`):
 
@@ -127,7 +154,7 @@ pnpm test
 pnpm run test:cli
 ```
 
-## Link locally so command works everywhere
+## 🔗 Link locally so command works everywhere
 
 ```bash
 # from setup-ruflo/
@@ -139,7 +166,7 @@ ruflo-setup --dry-run --skip-init
 
 This is the fast edit loop: change files in `src/`, rerun `ruflo-setup`, and behavior updates immediately without reinstall.
 
-## Simulate a real install (deploy-style testing)
+## 🧪 Simulate a real install (deploy-style testing)
 
 Create a tarball and install it into a clean test location.
 
@@ -154,7 +181,7 @@ ruflo-setup --dry-run --skip-init
 
 This tests exactly what users get from a package install.
 
-## Global hook behavior
+## 🪝 Global hook behavior
 
 `ruflo-setup` installs a global Claude SessionStart command hook that runs:
 

package/package.json

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

package/src/cli.js

@@ -18,6 +18,7 @@ function printHelp() {
 
 Usage:
   ruflo-setup [options]
+  ruflo-setup status
   ruflo-setup hooks install [options]
   ruflo-setup hooks status
 
@@ -32,6 +33,7 @@ Options:
 
 Examples:
   ruflo-setup
+  ruflo-setup status
   ruflo-setup --dry-run --skip-init
   ruflo-setup hooks status
   ruflo-setup hooks install --dry-run
@@ -58,6 +60,12 @@ export async function runCli(argv, cwd) {
     const packageRoot = packageRootFromModule();
     const flags = parseArgs(argv);
 
+    if (flags.command === 'status') {
+      const { runStatus } = await import('./status.js');
+      await runStatus({ cwd, packageRoot });
+      return 0;
+    }
+
     if (flags.command === 'hooks') {
       const subcommand = argv[1] || 'status';
       if (subcommand === 'status') {

package/src/status.js

@@ -0,0 +1,303 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { readJsonSafe } from './utils.js';
+import { getGlobalHookStatus } from './hooks.js';
+
+const require = createRequire(import.meta.url);
+const OK = '[OK]';
+const MISS = '[--]';
+const ERR = '[!!]';
+const IS_WIN = process.platform === 'win32';
+
+function spawn(cmd, args) {
+  try {
+    return spawnSync(cmd, args, {
+      stdio: ['ignore', 'pipe', 'ignore'],
+      encoding: 'utf8',
+      shell: IS_WIN
+    });
+  } catch {
+    return { status: 1, stdout: '' };
+  }
+}
+
+function dirExists(p) {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function fileExists(p) {
+  try {
+    return fs.statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+// Flatten npm/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)) {
+      map[name] = info?.version ?? true;
+      for (const [nname, ninfo] of Object.entries(info?.dependencies ?? {})) {
+        if (!(nname in map)) map[nname] = ninfo?.version ?? true;
+      }
+    }
+  } catch {
+    // ignore parse errors
+  }
+  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);
+  }
+  return {};
+}
+
+// Each checkLayer* returns { lines: string[], ok: number, total: number }
+
+function checkLayer0() {
+  const lines = [];
+  let ok = 0;
+  const nodeMajor = parseInt(process.version.slice(1), 10);
+  if (nodeMajor >= 20) { lines.push(`  ${OK} Node.js ${process.version}  (>=20 required)`); ok += 1; }
+  else { lines.push(`  ${ERR} Node.js ${process.version}  (>=20 required — upgrade Node.js)`); }
+
+  const pnpmRes = spawn('pnpm', ['--version']);
+  if (pnpmRes.status === 0 && pnpmRes.stdout.trim()) {
+    lines.push(`  ${OK} pnpm ${pnpmRes.stdout.trim()}`); ok += 1;
+  } else {
+    lines.push(`  ${MISS} pnpm  (install: npm install -g pnpm)`);
+  }
+
+  const claudeRes = spawn('claude', ['--version']);
+  if (claudeRes.status === 0) {
+    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)`);
+  }
+
+  if (process.env.ANTHROPIC_API_KEY) {
+    lines.push(`  ${OK} ANTHROPIC_API_KEY set`); ok += 1;
+  } else {
+    lines.push(`  ${ERR} ANTHROPIC_API_KEY not set  (required for LLM calls)`);
+  }
+
+  return { lines, ok, total: 4 };
+}
+
+function checkLayer1(pkgMap) {
+  const lines = [];
+  let ok = 0;
+  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})`); }
+  }
+  return { lines, ok, total: 2 };
+}
+
+function checkLayer2(pkgMap) {
+  const lines = [];
+  let ok = 0;
+  const ATTENTION_WIN_NOTE = '(Windows: requires Windows 11 SDK for NAPI; WASM fallback available)';
+  const pkgs = [
+    '@claude-flow/memory', '@ruvector/attention', '@claude-flow/aidefence', 'agentic-flow',
+    '@ruvector/sona', '@ruvector/router', '@ruvector/learning-wasm',
+    '@claude-flow/embeddings', '@claude-flow/guidance', '@claude-flow/codex'
+  ];
+  for (const name of pkgs) {
+    const ver = pkgMap[name];
+    if (ver) { lines.push(`  ${OK} ${name}${typeof ver === 'string' ? `@${ver}` : ''}`); ok += 1; }
+    else {
+      const note = (name === '@ruvector/attention' && IS_WIN) ? `  ${ATTENTION_WIN_NOTE}` : '';
+      lines.push(`  ${MISS} ${name}${note}`);
+    }
+  }
+  return { lines, ok, total: pkgs.length };
+}
+
+function checkLayer3(mcpJson) {
+  const lines = [];
+  let ok = 0;
+  const servers = mcpJson?.mcpServers ?? {};
+
+  if (servers['claude-flow']) {
+    const args = servers['claude-flow']?.args ?? [];
+    const pkgArg = args.find((a) => typeof a === 'string' && a.includes('@claude-flow/cli')) ?? '@claude-flow/cli@latest';
+    lines.push(`  ${OK} claude-flow  (${pkgArg})`); ok += 1;
+  } else {
+    lines.push(`  ${MISS} claude-flow  (run ruflo-setup to configure)`);
+  }
+
+  if (servers['ruv-swarm']) { lines.push(`  ${OK} ruv-swarm  (optional)`); ok += 1; }
+  else { lines.push(`  ${MISS} ruv-swarm  (optional)`); }
+
+  if (servers['flow-nexus']) { lines.push(`  ${OK} flow-nexus  (optional)`); ok += 1; }
+  else { lines.push(`  ${MISS} flow-nexus  (optional — needs Cognitum.One account)`); }
+
+  return { lines, ok, total: 3 };
+}
+
+function checkLayer4(mcpJson) {
+  const lines = [];
+  let ok = 0;
+  const cfEnv = mcpJson?.mcpServers?.['claude-flow']?.env ?? {};
+  const resolve = (k) => { const v = cfEnv[k] ?? process.env[k]; return v === undefined ? null : String(v).toLowerCase(); };
+
+  for (const g of ['INTELLIGENCE', 'AGENTS', 'MEMORY', 'DEVTOOLS']) {
+    if (resolve(`MCP_GROUP_${g}`) === 'false') { lines.push(`  ${MISS} ${g}    (disabled via MCP_GROUP_${g}=false)`); }
+    else { lines.push(`  ${OK} ${g}  (default on)`); ok += 1; }
+  }
+  for (const g of ['SECURITY', 'BROWSER', 'NEURAL', 'AGENTIC_FLOW']) {
+    if (resolve(`MCP_GROUP_${g}`) === 'true') { lines.push(`  ${OK} ${g}  (enabled)`); ok += 1; }
+    else { lines.push(`  ${MISS} ${g}    (set MCP_GROUP_${g}=true in .mcp.json env)`); }
+  }
+
+  return { lines, ok, total: 8 };
+}
+
+function checkLayer5() {
+  const lines = [];
+  let ok = 0;
+  const checks = [
+    { key: 'ANTHROPIC_API_KEY', req: true, note: '' },
+    { key: 'OPENAI_API_KEY', req: false, note: '(optional — enables GPT + Codex)' },
+    { key: 'GOOGLE_API_KEY', req: false, note: '(optional — enables Gemini)' },
+    { key: 'OPENROUTER_API_KEY', req: false, note: '(optional — multi-provider proxy)' }
+  ];
+  for (const { key, req, note } of checks) {
+    if (process.env[key]) { lines.push(`  ${OK} ${key}`); ok += 1; }
+    else if (req) { lines.push(`  ${ERR} ${key} not set  (required for LLM calls)`); }
+    else { lines.push(`  ${MISS} ${key}  ${note}`); }
+  }
+  return { lines, ok, total: checks.length };
+}
+
+function checkLayer6(packageRoot) {
+  const lines = [];
+  let ok = 0;
+  const homeDir = os.homedir();
+
+  try {
+    const hs = getGlobalHookStatus({ packageRoot });
+    const sp = hs.settingsPath ?? path.join(homeDir, '.claude', 'settings.json');
+    if (hs.installed) { lines.push(`  ${OK} SessionStart hook  (${sp})`); ok += 1; }
+    else { lines.push(`  ${MISS} SessionStart hook  (${sp})`); }
+  } catch {
+    lines.push(`  ${MISS} SessionStart hook  (could not read ~/.claude/settings.json)`);
+  }
+
+  const commandFile = path.join(homeDir, '.claude', 'commands', 'ruflo-setup.md');
+  if (fileExists(commandFile)) { lines.push(`  ${OK} /ruflo-setup command  (${commandFile})`); ok += 1; }
+  else { lines.push(`  ${MISS} /ruflo-setup command  (${commandFile})`); }
+
+  return { lines, ok, total: 2 };
+}
+
+function checkLayer7(cwd) {
+  const lines = [];
+  let ok = 0;
+  const files = ['.mcp.json', 'CLAUDE.md', path.join('.claude', 'settings.json')];
+  const dirs = [
+    { rel: path.join('.claude', 'agents'), hint: 'run: ruflo init --full' },
+    { rel: path.join('.claude', 'skills'), hint: null },
+    { rel: path.join('.claude', 'commands'), hint: null },
+    { rel: '.claude-flow', hint: null }
+  ];
+
+  for (const rel of files) {
+    if (fileExists(path.join(cwd, rel))) { lines.push(`  ${OK} ${rel}`); ok += 1; }
+    else { lines.push(`  ${MISS} ${rel}`); }
+  }
+  for (const { rel, hint } of dirs) {
+    const disp = `${rel}/`.replace(/\\/g, '/');
+    const full = path.join(cwd, rel);
+    if (dirExists(full)) {
+      let count = '';
+      if (rel.endsWith('agents') || rel.endsWith('skills')) {
+        try {
+          const n = fs.readdirSync(full).length;
+          const label = rel.endsWith('agents') ? 'agents' : 'skills';
+          count = `  (${n} ${label})`;
+        } catch { /* ignore */ }
+      }
+      lines.push(`  ${OK} ${disp}${count}`); ok += 1;
+    } else {
+      lines.push(`  ${MISS} ${disp}${hint ? `  (${hint})` : ''}`);
+    }
+  }
+
+  return { lines, ok, total: files.length + dirs.length };
+}
+
+function checkLayer8() {
+  const res = spawn('docker', ['--version']);
+  if (res.status === 0 && res.stdout.trim()) {
+    return { lines: [`  ${OK} Docker  ${res.stdout.trim()}`], ok: 1, total: 1 };
+  }
+  return { lines: [`  ${MISS} Docker not detected  (optional — needed for ruvocal chat UI)`], ok: 0, total: 1 };
+}
+
+export async function runStatus({ cwd, packageRoot }) {
+  try {
+    const { version } = require('../package.json');
+    const mcpJson = readJsonSafe(path.join(cwd, '.mcp.json'), {});
+    const pkgMap = getGlobalPkgMap();
+
+    const layers = [
+      { title: 'Layer 0: Prerequisites', result: checkLayer0() },
+      { title: 'Layer 1: Global npm 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) },
+      { title: 'Layer 5: Environment Variables', result: checkLayer5() },
+      { title: 'Layer 6: Claude Code Hooks', result: checkLayer6(packageRoot) },
+      { title: 'Layer 7: Project Scaffolding', result: checkLayer7(cwd) },
+      { title: 'Layer 8: Docker Chat UI  (optional)', result: checkLayer8() }
+    ];
+
+    let totalOk = 0;
+    let totalChecks = 0;
+
+    process.stdout.write(`\nRuflo Feature Status  (ruflo-setup v${version})\n`);
+    process.stdout.write(`Target: ${cwd}\n`);
+
+    for (const { title, result } of layers) {
+      process.stdout.write(`\n${title}\n`);
+      for (const line of result.lines) process.stdout.write(`${line}\n`);
+      totalOk += result.ok;
+      totalChecks += result.total;
+    }
+
+    process.stdout.write(`\nSummary: ${totalOk}/${totalChecks} features enabled\n`);
+    process.stdout.write(`For agents, skills, and slash commands reference: docs/ruflo-benefit.md\n`);
+
+    const hasRequiredMissing = parseInt(process.version.slice(1), 10) < 20 || !process.env.ANTHROPIC_API_KEY;
+    if (hasRequiredMissing) process.stdout.write(`Run 'ruflo-setup' to configure missing required features.\n`);
+    process.stdout.write('\n');
+  } catch (error) {
+    process.stderr.write(`status error: ${error.message}\n`);
+  }
+}

package/src/utils.js

@@ -90,7 +90,11 @@ export function toPlatformMcpConfig(platform) {
           CLAUDE_FLOW_HOOKS_ENABLED: 'true',
           CLAUDE_FLOW_TOPOLOGY: 'hierarchical-mesh',
           CLAUDE_FLOW_MAX_AGENTS: '15',
-          CLAUDE_FLOW_MEMORY_BACKEND: 'hybrid'
+          CLAUDE_FLOW_MEMORY_BACKEND: 'hybrid',
+          MCP_GROUP_SECURITY: 'true',
+          MCP_GROUP_BROWSER: 'true',
+          MCP_GROUP_NEURAL: 'true',
+          MCP_GROUP_AGENTIC_FLOW: 'true'
         },
         autoStart: false
       },