cf-doctor 1.0.0

package/patches/README.md

@@ -0,0 +1,68 @@
+# @ruvector/* Import Fix Patches
+
+These patches fix crashes that occur when `@ruvector/*` WASM packages are not
+installed. Each patch converts a hard static import into a dynamic import with
+an in-memory fallback, so claude-flow runs correctly without the optional native
+backends.
+
+## Patches
+
+| File | Target Repo | Severity | Description |
+|------|------------|----------|-------------|
+| `sona-integration.patch` | claude-flow | CRITICAL | Replaces static `@ruvector/sona` import with lazy dynamic import + MockSonaEngine fallback |
+| `neural-index.patch` | claude-flow | CRITICAL | Updates barrel file comments; safe once sona-integration is patched |
+| `quick-test.patch` | claude-flow | LOW | Replaces static `@ruvector/attention` import in benchmark example |
+| `version-bridge.patch` | ruvector | NORMAL | Detects claude-flow v2 vs v3 CLI syntax before spawning hooks |
+
+## Apply Instructions
+
+### claude-flow repo (Patches A, B, C)
+
+```bash
+cd claude-flow
+git apply /tmp/cf-integration-fixes/patches/sona-integration.patch
+git apply /tmp/cf-integration-fixes/patches/neural-index.patch
+git apply /tmp/cf-integration-fixes/patches/quick-test.patch
+```
+
+### ruvector repo (Patch D)
+
+```bash
+cd ruvector
+git apply /tmp/cf-integration-fixes/patches/version-bridge.patch
+```
+
+### Dry-run (check without applying)
+
+```bash
+git apply --check /tmp/cf-integration-fixes/patches/sona-integration.patch
+```
+
+### Reverse a patch
+
+```bash
+git apply -R /tmp/cf-integration-fixes/patches/sona-integration.patch
+```
+
+## Verification
+
+After applying, confirm no static `@ruvector/*` imports remain in critical paths:
+
+```bash
+# Should return zero results for patched files
+grep -rn "from '@ruvector/" v3/@claude-flow/neural/src/sona-integration.ts
+grep -rn "from '@ruvector/" v3/@claude-flow/performance/src/examples/quick-test.ts
+```
+
+Test that the mock fallback activates cleanly (without @ruvector installed):
+
+```bash
+npx tsx -e "
+  import { SonaIntegration } from './v3/@claude-flow/neural/index';
+  const s = new SonaIntegration();
+  s.storePattern('test', { v: 1 }).then(() => {
+    console.log('mock:', s.isUsingMock());
+    return s.recallPattern('test');
+  }).then(r => console.log('recalled:', r));
+"
+```

package/patches/neural-index.patch

@@ -0,0 +1,8 @@
+--- a/v3/@claude-flow/neural/index.ts
++++ b/v3/@claude-flow/neural/index.ts
+@@ -1,3 +1,4 @@
+ export { SonaIntegration } from './src/sona-integration';
+ export { NeuralRouter } from './src/neural-router';
+-// ... other exports that depend on @ruvector
++// Re-exports are safe now because sona-integration uses dynamic import internally
++// No @ruvector/* static imports leak through this barrel file

package/patches/quick-test.patch

@@ -0,0 +1,25 @@
+--- a/v3/@claude-flow/performance/src/examples/quick-test.ts
++++ b/v3/@claude-flow/performance/src/examples/quick-test.ts
+@@ -1,7 +1,19 @@
+-import { FlashAttention } from '@ruvector/attention';
+-
+ async function runBenchmark() {
+-  const attn = new FlashAttention({ headDim: 64 });
++  let FlashAttention: any;
++  try {
++    const mod = await import('@ruvector/attention');
++    FlashAttention = mod.FlashAttention;
++  } catch {
++    console.warn('[perf] @ruvector/attention not available, using mock');
++    FlashAttention = class MockFlashAttention {
++      constructor(private opts: any) {}
++      async forward(q: any, k: any, v: any) {
++        // Mock: return zero tensor of expected shape
++        return { output: new Float32Array(this.opts.headDim || 64), mockResult: true };
++      }
++    };
++  }
++
++  const attn = new FlashAttention({ headDim: 64 });
+   // ...rest of benchmark
+ }

package/patches/sona-integration.patch

@@ -0,0 +1,76 @@
+--- a/v3/@claude-flow/neural/src/sona-integration.ts
++++ b/v3/@claude-flow/neural/src/sona-integration.ts
+@@ -1,27 +1,55 @@
+-import { SonaEngine } from '@ruvector/sona';
++// Dynamic import with fallback - @ruvector/sona is optional
++let SonaEngineImpl: any = null;
+
+-export class SonaIntegration {
+-  private engine: SonaEngine;
++async function loadSonaEngine(): Promise<any> {
++  if (SonaEngineImpl !== null) return SonaEngineImpl;
++  try {
++    const mod = await import('@ruvector/sona');
++    SonaEngineImpl = mod.SonaEngine;
++    return SonaEngineImpl;
++  } catch {
++    // @ruvector/sona not installed - use in-memory mock
++    SonaEngineImpl = class MockSonaEngine {
++      private store = new Map<string, any>();
+
+-  constructor() {
+-    this.engine = new SonaEngine();
+-  }
++      async store(key: string, pattern: any): Promise<void> {
++        this.store.set(key, pattern);
++      }
+
+-  async storePattern(key: string, pattern: any): Promise<void> {
+-    await this.engine.store(key, pattern);
+-  }
++      async recall(key: string): Promise<any> {
++        return this.store.get(key) ?? null;
++      }
+
+-  async recallPattern(key: string): Promise<any> {
+-    return this.engine.recall(key);
++      async learn(_input: any, _feedback: number): Promise<void> {
++        // Mock: no-op learning without SONA neural backend
++      }
++    };
++    return SonaEngineImpl;
+   }
++}
+
+-  async learn(input: any, feedback: number): Promise<void> {
+-    await this.engine.learn(input, feedback);
++export class SonaIntegration {
++  private engine: any = null;
++  private initialized = false;
++
++  private async ensureInit(): Promise<void> {
++    if (this.initialized) return;
++    const Engine = await loadSonaEngine();
++    this.engine = new Engine();
++    this.initialized = true;
++  }
++
++  async storePattern(key: string, pattern: any): Promise<void> {
++    await this.ensureInit();
++    await this.engine.store(key, pattern);
++  }
++
++  async recallPattern(key: string): Promise<any> {
++    await this.ensureInit();
++    return this.engine.recall(key);
++  }
++
++  async learn(input: any, feedback: number): Promise<void> {
++    await this.ensureInit();
++    await this.engine.learn(input, feedback);
++  }
++
++  isUsingMock(): boolean {
++    return SonaEngineImpl?.name === 'MockSonaEngine';
+   }
+ }

package/patches/version-bridge.patch

@@ -0,0 +1,30 @@
+--- a/npm/packages/agentic-integration/swarm-manager.ts
++++ b/npm/packages/agentic-integration/swarm-manager.ts
+@@ -1,4 +1,25 @@
++async function detectClaudeFlowVersion(): Promise<'v2' | 'v3' | null> {
++  try {
++    const { stdout } = await execAsync('npx claude-flow --version 2>/dev/null');
++    const version = stdout.trim();
++    if (version.startsWith('3.') || version.startsWith('v3.')) return 'v3';
++    if (version.startsWith('2.') || version.startsWith('v2.') || version.includes('alpha')) return 'v2';
++    return 'v3'; // default to v3 for newer versions
++  } catch {
++    return null;
++  }
++}
++
+ async function registerHooks(config: SwarmConfig) {
+-  const proc = spawn('npx', ['claude-flow@alpha', 'hooks', 'register', '--swarm', config.name]);
++  const cfVersion = await detectClaudeFlowVersion();
++  if (!cfVersion) {
++    console.warn('[swarm-manager] claude-flow not found, skipping hook registration');
++    return;
++  }
++
++  const args = cfVersion === 'v3'
++    ? ['claude-flow', 'mcp', '--hooks', JSON.stringify({ swarm: config.name })]
++    : ['claude-flow@alpha', 'hooks', 'register', '--swarm', config.name];
++
++  const proc = spawn('npx', args);
+   // ...
+ }