Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

test(mods): check that every tool name a plugin guard watches exists in the registry

ruv00eed549d43c
diff --git a/.github/workflows/all-plugins-smoke.yml b/.github/workflows/all-plugins-smoke.yml
index 19b515ea32..0a9fa2157b 100644
--- a/.github/workflows/all-plugins-smoke.yml
+++ b/.github/workflows/all-plugins-smoke.yml
@@ -18,12 +18,20 @@ on:
- 'plugins/**'
- 'scripts/smoke-all-plugins.mjs'
- 'scripts/audit-plugin-mcp-prefix.mjs'
+ - 'scripts/check-guard-tool-names.mjs'
+ - 'scripts/guard-tool-names.allow.json'
+ - 'v3/@claude-flow/cli/src/mcp-tools/**'
+ - 'v3/@claude-flow/cli/src/ruvector/coverage-tools.ts'
- '.github/workflows/all-plugins-smoke.yml'
pull_request:
paths:
- 'plugins/**'
- 'scripts/smoke-all-plugins.mjs'
- 'scripts/audit-plugin-mcp-prefix.mjs'
+ - 'scripts/check-guard-tool-names.mjs'
+ - 'scripts/guard-tool-names.allow.json'
+ - 'v3/@claude-flow/cli/src/mcp-tools/**'
+ - 'v3/@claude-flow/cli/src/ruvector/coverage-tools.ts'
- '.github/workflows/all-plugins-smoke.yml'
workflow_dispatch:
@@ -47,6 +55,14 @@ jobs:
# smoke while letting the metaharness fleet finish.
run: node scripts/smoke-all-plugins.mjs --timeout 300
+ - name: Guard tool names exist in the registry
+ run: |
+ node --test tests/check-guard-tool-names.test.mjs
+ node scripts/check-guard-tool-names.mjs
+ # A renamed MCP tool leaves a plugin guard watching a name that no
+ # longer exists, so it silently stops guarding. Fails loud if zero
+ # names are extracted or the registry is empty.
+
- name: Fleet-wide exit-bypass antipattern lint (iter-75 bug class)
run: node scripts/audit-exit-bypass-antipattern.mjs
# Static analyzer: scans every plugins/*/scripts/*.mjs for the
diff --git a/scripts/check-guard-tool-names.mjs b/scripts/check-guard-tool-names.mjs
new file mode 100644
index 0000000000..d20819e02b
--- /dev/null
+++ b/scripts/check-guard-tool-names.mjs
@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+// check-guard-tool-names — every MCP tool name a plugin mod guard watches by string must
+// exist in the real tool registry, or the guard silently stops guarding after a rename.
+//
+// node scripts/check-guard-tool-names.mjs [--verbose] [--format json]
+//
+// Watched names: quoted tool-shaped strings in plugins/*/hooks/*.ts whose first segment is a
+// known tool family (a family seen in the registry or the allowlist), so event names such as
+// `in_progress` or `text_delta` are not mistaken for tools.
+// Registry: `name: '...'` in v3/@claude-flow/cli/src/mcp-tools/*.ts, plus the tools a plugin's
+// own server declares (plugins with a .mcp.json: `.tool('x'` / `registerTool('x'` in src/).
+// Allowlist: scripts/guard-tool-names.allow.json, name -> reason (tools other servers serve).
+//
+// Exit: 0 clean · 1 unmatched watched names · 3 nothing extracted / empty registry (fail loud).
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const SHAPE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*_[a-z0-9]+(?:[_-][a-z0-9]+)*$/;
+const QUOTED = /(['"`])([a-z][a-z0-9_-]*)\1/g;
+const family = (name) => name.split('_')[0];
+
+/** Quoted strings in `source` that have the tool-name shape. */
+export function extractCandidates(source) {
+ const found = new Set();
+ for (const m of source.matchAll(QUOTED)) if (SHAPE.test(m[2])) found.add(m[2]);
+ return found;
+}
+
+/** Tool names a core tool module declares: `name: '...'` with the tool shape. */
+export function extractRegistryNames(source) {
+ const found = new Set();
+ for (const m of source.matchAll(/\bname:\s*(['"`])([a-z][a-z0-9_-]*)\1/g)) if (SHAPE.test(m[2])) found.add(m[2]);
+ return found;
+}
+
+/** Tool names a plugin's own MCP server registers. Their server-local names have no family prefix rule. */
+export function extractServerNames(source) {
+ const found = new Set();
+ for (const m of source.matchAll(/(?:\.tool|registerTool)\(\s*(['"`])([a-z][a-z0-9_-]*)\1/g)) found.add(m[2]);
+ return found;
+}
+
+/**
+ * Split the candidates into those to check and those ignored (family unknown), then report
+ * the unmatched. `registry` and `allow` are Set / plain object.
+ */
+export function check(watched, registry, allow) {
+ const families = new Set([...registry, ...Object.keys(allow)].map(family));
+ const checked = [];
+ const ignored = [];
+ for (const name of [...watched].sort()) (families.has(family(name)) ? checked : ignored).push(name);
+ const unmatched = checked.filter((n) => !registry.has(n) && !(n in allow));
+ return { checked, ignored, unmatched, allowed: checked.filter((n) => !registry.has(n) && n in allow) };
+}
+
+const tsFiles = (dir) => (existsSync(dir) ? readdirSync(dir).filter((f) => f.endsWith('.ts') && !/\.(test|spec)\.ts$/.test(f)).map((f) => join(dir, f)) : []);
+
+function walk(dir, out = []) {
+ if (!existsSync(dir)) return out;
+ for (const e of readdirSync(dir, { withFileTypes: true })) {
+ if (e.name === 'node_modules') continue;
+ const p = join(dir, e.name);
+ if (e.isDirectory()) walk(p, out);
+ else if (/\.(mjs|cjs|js|ts)$/.test(e.name)) out.push(p);
+ }
+ return out;
+}
+
+/** Gather watched names (name -> plugins) and the registry from the repo on disk. */
+export function gather(root = ROOT) {
+ const watched = new Map();
+ const registry = new Set();
+ const plugins = join(root, 'plugins');
+ for (const p of readdirSync(plugins)) {
+ for (const f of tsFiles(join(plugins, p, 'hooks'))) {
+ for (const n of extractCandidates(readFileSync(f, 'utf8'))) watched.set(n, [...(watched.get(n) ?? []), p]);
+ }
+ if (existsSync(join(plugins, p, '.mcp.json'))) {
+ for (const f of walk(join(plugins, p, 'src'))) for (const n of extractServerNames(readFileSync(f, 'utf8'))) registry.add(n);
+ }
+ }
+ // mcp-tools/ holds most tools; ruvector/coverage-tools.ts is the one tool module outside it.
+ const cli = join(root, 'v3/@claude-flow/cli/src');
+ const toolFiles = [...tsFiles(join(cli, 'mcp-tools')), join(cli, 'ruvector/coverage-tools.ts')].filter(existsSync);
+ for (const f of toolFiles) for (const n of extractRegistryNames(readFileSync(f, 'utf8'))) registry.add(n);
+ const allowPath = join(root, 'scripts/guard-tool-names.allow.json');
+ const allow = existsSync(allowPath) ? JSON.parse(readFileSync(allowPath, 'utf8')) : {};
+ return { watched, registry, allow };
+}
+
+function main() {
+ const verbose = process.argv.includes('--verbose');
+ const json = process.argv.includes('--format') && process.argv[process.argv.indexOf('--format') + 1] === 'json';
+ const { watched, registry, allow } = gather();
+ if (watched.size === 0 || registry.size === 0) {
+ console.error(`check-guard-tool-names: extracted ${watched.size} watched names and ${registry.size} registry names; one is zero, so the check is broken (repo layout drift?). Failing.`);
+ process.exit(3);
+ }
+ const r = check(new Set(watched.keys()), registry, allow);
+ if (r.checked.length === 0) {
+ console.error('check-guard-tool-names: no watched name belongs to a known tool family; the check is broken. Failing.');
+ process.exit(3);
+ }
+ const stale = Object.keys(allow).filter((n) => registry.has(n));
+ if (json) console.log(JSON.stringify({ watched: watched.size, checked: r.checked.length, registry: registry.size, allowed: r.allowed, unmatched: r.unmatched, staleAllow: stale }));
+ else {
+ console.log(`check-guard-tool-names: ${r.checked.length} watched tool names checked (${r.ignored.length} non-tool strings ignored) against ${registry.size} registry names; ${r.allowed.length} allowlisted.`);
+ if (verbose) console.log(`allowlisted: ${r.allowed.join(', ')}\nignored: ${r.ignored.join(', ')}`);
+ for (const n of stale) console.log(`note: allowlist entry "${n}" is now in the registry; remove it.`);
+ for (const n of r.unmatched) console.error(`UNMATCHED ${n} (watched by ${[...new Set(watched.get(n))].join(', ')}): no such tool in the registry. Renamed or removed? Fix the guard or add it to scripts/guard-tool-names.allow.json with a reason.`);
+ }
+ process.exit(r.unmatched.length ? 1 : 0);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main();
diff --git a/scripts/guard-tool-names.allow.json b/scripts/guard-tool-names.allow.json
new file mode 100644
index 0000000000..93ec6e1ebb
--- /dev/null
+++ b/scripts/guard-tool-names.allow.json
@@ -0,0 +1,8 @@
+{
+ "hooks_recall": "ruvector MCP server (npx ruvector), not the ruflo CLI registry",
+ "hooks_remember": "ruvector MCP server (npx ruvector), not the ruflo CLI registry",
+ "hooks_learn": "ruvector MCP server (npx ruvector), not the ruflo CLI registry",
+ "hooks_compress_store": "ruvector MCP server (npx ruvector), not the ruflo CLI registry",
+ "agent_message": "a Claude Code stream-event type the console renders, not an MCP tool",
+ "mcp_tool_call": "a Codex stream-event type the console renders, not an MCP tool"
+}
diff --git a/tests/check-guard-tool-names.test.mjs b/tests/check-guard-tool-names.test.mjs
new file mode 100644
index 0000000000..0fa7a91241
--- /dev/null
+++ b/tests/check-guard-tool-names.test.mjs
@@ -0,0 +1,106 @@
+// node --test tests/check-guard-tool-names.test.mjs
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { cpSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+import { check, extractCandidates, extractRegistryNames, extractServerNames, gather } from '../scripts/check-guard-tool-names.mjs';
+
+const SCRIPT = fileURLToPath(new URL('../scripts/check-guard-tool-names.mjs', import.meta.url));
+
+test('extractCandidates keeps quoted tool-shaped names only', () => {
+ const src = "const W = new Set(['agentdb_hierarchical-store', `memory_store`, \"x_federation_publish\", 'plain', 'Not_Shaped', 'a b_c'])";
+ assert.deepEqual([...extractCandidates(src)].sort(), ['agentdb_hierarchical-store', 'memory_store', 'x_federation_publish']);
+});
+
+test('extractRegistryNames reads name: fields', () => {
+ assert.deepEqual([...extractRegistryNames("{ name: 'memory_store', description: 'x' }, { name: \"hooks_pre-edit\" }, { name: 'plain' }")].sort(), ['hooks_pre-edit', 'memory_store']);
+});
+
+test('extractServerNames reads .tool( and registerTool( calls', () => {
+ assert.deepEqual([...extractServerNames("mcp.tool('claims_issue', 'd', {}); server.registerTool(\"channel_list\", {})")].sort(), ['channel_list', 'claims_issue']);
+});
+
+test('check reports a watched name that has no registry match', () => {
+ const r = check(new Set(['memory_store', 'memory_stor']), new Set(['memory_store']), {});
+ assert.deepEqual(r.unmatched, ['memory_stor']);
+});
+
+test('check ignores strings whose family is unknown, but not those in a known family', () => {
+ const r = check(new Set(['in_progress', 'text_delta', 'memory_gone']), new Set(['memory_store']), {});
+ assert.deepEqual(r.ignored, ['in_progress', 'text_delta']);
+ assert.deepEqual(r.unmatched, ['memory_gone']);
+});
+
+test('check honours the allowlist and reports it as allowed', () => {
+ const r = check(new Set(['hooks_recall']), new Set(['hooks_route']), { hooks_recall: 'ruvector' });
+ assert.deepEqual(r.unmatched, []);
+ assert.deepEqual(r.allowed, ['hooks_recall']);
+});
+
+function fixture(files) {
+ const root = mkdtempSync(join(tmpdir(), 'guard-names-'));
+ for (const [path, body] of Object.entries(files)) {
+ mkdirSync(join(root, path, '..'), { recursive: true });
+ writeFileSync(join(root, path), body);
+ }
+ return root;
+}
+
+test('gather skips test files, reads plugin server names, and merges the allowlist', () => {
+ const root = fixture({
+ 'plugins/p/hooks/guard.ts': "const W = ['memory_store', 'channel_list']",
+ 'plugins/p/hooks/guard.test.ts': "const W = ['memory_ghost']",
+ 'plugins/p/.mcp.json': '{}',
+ 'plugins/p/src/server.mjs': "mcp.tool('channel_list', 'd')",
+ 'v3/@claude-flow/cli/src/mcp-tools/memory-tools.ts': "{ name: 'memory_store' }",
+ 'scripts/guard-tool-names.allow.json': '{"x_y":"r"}',
+ });
+ try {
+ const g = gather(root);
+ assert.deepEqual([...g.watched.keys()].sort(), ['channel_list', 'memory_store']);
+ assert.deepEqual([...g.registry].sort(), ['channel_list', 'memory_store']);
+ assert.deepEqual(g.allow, { x_y: 'r' });
+ } finally {
+ rmSync(root, { recursive: true, force: true });
+ }
+});
+
+function runIn(files) {
+ const root = fixture(files);
+ mkdirSync(join(root, 'scripts'), { recursive: true });
+ cpSync(SCRIPT, join(root, 'scripts/check-guard-tool-names.mjs'));
+ try {
+ return spawnSync(process.execPath, [join(root, 'scripts/check-guard-tool-names.mjs')], { encoding: 'utf8' });
+ } finally {
+ rmSync(root, { recursive: true, force: true });
+ }
+}
+
+test('CLI fails loud (exit 3) when nothing was extracted', () => {
+ const r = runIn({ 'plugins/p/hooks/guard.ts': 'export {}', 'v3/@claude-flow/cli/src/mcp-tools/a.ts': "{ name: 'memory_store' }" });
+ assert.equal(r.status, 3);
+ assert.match(r.stderr, /check is broken/);
+});
+
+test('CLI fails loud (exit 3) when the registry is empty', () => {
+ const r = runIn({ 'plugins/p/hooks/guard.ts': "['memory_store']", 'v3/@claude-flow/cli/src/mcp-tools/a.ts': 'export {}' });
+ assert.equal(r.status, 3);
+});
+
+test('CLI exits 1 naming the plugin for a renamed tool, 0 once it matches', () => {
+ const base = { 'plugins/p/hooks/guard.ts': "['memory_store', 'memory_renamed']" };
+ const bad = runIn({ ...base, 'v3/@claude-flow/cli/src/mcp-tools/a.ts': "{ name: 'memory_store' }" });
+ assert.equal(bad.status, 1);
+ assert.match(bad.stderr, /UNMATCHED memory_renamed \(watched by p\)/);
+ const ok = runIn({ ...base, 'v3/@claude-flow/cli/src/mcp-tools/a.ts': "{ name: 'memory_store' }, { name: 'memory_renamed' }" });
+ assert.equal(ok.status, 0);
+});
+
+test('the real repo passes', () => {
+ const r = spawnSync(process.execPath, [SCRIPT], { encoding: 'utf8' });
+ assert.equal(r.status, 0, r.stderr);
+});