{"record":{"id":"7bf5e811732a0127","repo":"ruvnet/ruflo","slug":"ruvbot-is-not-installed-install-it-with-npm-inst","errorCode":null,"errorMessage":"ruvbot is not installed. Install it with: npm install ruvbot@0.1.8\nruvbot is an optional peer dependency of @claude-flow/guidance.","messagePattern":"ruvbot is not installed\\. Install it with: npm install ruvbot@0\\.1\\.8\nruvbot is an optional peer dependency of @claude-flow/guidance\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/guidance/src/ruvbot-integration.ts","lineNumber":183,"sourceCode":" * Module specifiers kept in variables so TypeScript does not attempt\n * compile-time resolution of this optional peer dependency.\n */\nconst RUVBOT_MODULE = 'ruvbot';\nconst RUVBOT_CORE_MODULE = 'ruvbot/core';\n\n/**\n * Attempt to dynamically import the ruvbot package.\n * Throws a descriptive error if the package is not installed.\n */\nasync function requireRuvBot(): Promise<Record<string, unknown>> {\n  if (ruvbotModuleCache) return ruvbotModuleCache;\n\n  try {\n    const mod = await import(RUVBOT_MODULE) as Record<string, unknown>;\n    ruvbotModuleCache = mod;\n    return mod;\n  } catch {\n    throw new Error(\n      'ruvbot is not installed. Install it with: npm install ruvbot@0.1.8\\n' +\n      'ruvbot is an optional peer dependency of @claude-flow/guidance.',\n    );\n  }\n}\n\n/**\n * Attempt to dynamically import ruvbot/core sub-export.\n */\nasync function requireRuvBotCore(): Promise<Record<string, unknown>> {\n  try {\n    return await import(RUVBOT_CORE_MODULE) as Record<string, unknown>;\n  } catch {\n    // Fall back to the main export\n    return requireRuvBot();\n  }\n}\n","sourceCodeStart":165,"sourceCodeEnd":201,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/guidance/src/ruvbot-integration.ts#L165-L201","documentation":"The ruvbot integration (AIDefenceGate and friends) lazily dynamic-imports the 'ruvbot' package on first use; if module resolution fails it throws this error with install instructions because ruvbot is an optional peer dependency that @claude-flow/guidance does not install for you. The failed import is not cached, so the error repeats until the package is actually present.","triggerScenarios":"Constructing or first-using AIDefenceGate / RuvBotMemoryAdapter / RuvBotGuidanceBridge without ruvbot installed; CI images or --production installs that prune optional peer deps; monorepo hoisting that removes the package from the resolution path.","commonSituations":"Enabling AI-defence features (prompt-injection, jailbreak, PII detection) in an environment where the dependency was never added; fresh clones relying on a colleague's global install; Docker images built from a trimmed dependency tree.","solutions":["Install the expected version: npm install ruvbot@0.1.8","If you do not use AI-defence features, do not construct AIDefenceGate — nothing else needs ruvbot","If you ship code paths that use the gate, declare ruvbot in your own package.json dependencies so installs are deterministic","Verify resolution in the target environment: node -e \"import('ruvbot').then(() => console.log('ok'), e => process.exit(1))\""],"exampleFix":"// before\nconst gate = new AIDefenceGate({}); // first use throws: ruvbot not installed\n// after (shell)\n// npm install ruvbot@0.1.8\n// after (optional runtime feature-detect)\nconst hasRuvbot = await import('ruvbot').then(() => true, () => false);\nconst gate = hasRuvbot ? new AIDefenceGate({}) : null;","handlingStrategy":"validation","validationCode":"// feature-detect before enabling ruvbot-backed gates\nconst hasRuvbot = await import('ruvbot').then(() => true, () => false);\nif (config.enableAiDefence && !hasRuvbot) {\n  throw new Error('AI defence requested but ruvbot is not installed. Run: npm install ruvbot@0.1.8');\n}","typeGuard":"async function canUseAIDefence(): Promise<boolean> {\n  try {\n    await import('ruvbot');\n    return true;\n  } catch {\n    return false;\n  }\n}","tryCatchPattern":"try {\n  const gate = new AIDefenceGate({});\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('ruvbot is not installed')) {\n    // degrade gracefully or fail config validation; installing is the real fix\n    logger.warn('AI defence disabled: optional dependency ruvbot missing');\n  } else {\n    throw err;\n  }\n}","preventionTips":["Declare ruvbot in package.json dependencies if any shipped code path constructs AIDefenceGate","Add a CI check that optional peers resolve when the feature flag is on","Docker/production installs prune optional peer deps — install ruvbot explicitly"],"tags":["guidance","ruvbot","peer-dependency","optional-dependency","installation"],"backgroundTag":"missing-peer-dependency","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}