claude-brain 0.3.7 → 0.4.1

package/VERSION

@@ -1 +1 @@
-0.3.7
+0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-brain",
-  "version": "0.3.7",
+  "version": "0.4.1",
   "description": "Local development assistant bridging Obsidian vaults with Claude Code via MCP",
   "type": "module",
   "main": "src/index.ts",

package/src/cli/auto-setup.ts

@@ -8,6 +8,14 @@ function getDefaultEnv(vaultPath: string): string {
 VAULT_PATH=${vaultPath}
 LOG_LEVEL=info
 NODE_ENV=production
+
+# ChromaDB Configuration
+# Start ChromaDB server: claude-brain chroma start
+# Install ChromaDB: claude-brain chroma install
+CHROMA_MODE=client-server
+CHROMA_HOST=localhost
+CHROMA_PORT=8000
+CHROMA_EMBEDDING_PROVIDER=transformers
 `
 }
 

package/src/cli/bin.ts

@@ -31,6 +31,7 @@ function printHelp() {
     ['install', 'Register as MCP server in Claude Code'],
     ['uninstall', 'Remove MCP server from Claude Code'],
     ['update', 'Update package and refresh CLAUDE.md'],
+    ['chroma', 'Manage ChromaDB server (start/stop/status)'],
     ['health', 'Run health checks'],
     ['diagnose', 'Run diagnostics'],
     ['version', 'Show version'],
@@ -58,6 +59,7 @@ function printHelp() {
     `  ${dimText('claude-brain setup')}           ${dimText('Configure Claude Brain')}`,
     `  ${dimText('claude-brain install')}         ${dimText('Register with Claude Code')}`,
     `  ${dimText('claude-brain update')}          ${dimText('Update to latest version')}`,
+    `  ${dimText('claude-brain chroma start')}    ${dimText('Start ChromaDB server')}`,
     `  ${dimText('claude-brain health')}          ${dimText('Check system health')}`,
     '',
     theme.bold('Environment:'),
@@ -102,6 +104,12 @@ async function main() {
       break
     }
 
+    case 'chroma': {
+      const { runChroma } = await import('./commands/chroma')
+      await runChroma()
+      break
+    }
+
     case 'health': {
       const { runHealthCheck } = await import('@/health')
       await runHealthCheck()

package/src/cli/commands/chroma.ts

@@ -0,0 +1,407 @@
+/**
+ * ChromaDB Management Command
+ * Start, stop, and manage the ChromaDB server for Claude Brain
+ */
+
+import { spawn, execSync } from 'node:child_process'
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs'
+import { join } from 'node:path'
+import { getHomePaths } from '@/config/home'
+import {
+  theme, heading, successText, errorText, warningText, dimText,
+  infoPanel,
+} from '@/cli/ui/index.js'
+
+const PID_FILENAME = 'chroma.pid'
+const DEFAULT_PORT = '8000'
+
+function getPidFilePath(): string {
+  const paths = getHomePaths()
+  return join(paths.data, PID_FILENAME)
+}
+
+function getChromaDataPath(): string {
+  const paths = getHomePaths()
+  return paths.chroma
+}
+
+function isChromaCliInstalled(): boolean {
+  try {
+    execSync('chroma --version', { stdio: 'pipe', timeout: 5000 })
+    return true
+  } catch {
+    return false
+  }
+}
+
+function getChromaVersion(): string {
+  try {
+    return execSync('chroma --version', { encoding: 'utf-8', stdio: 'pipe', timeout: 5000 }).trim()
+  } catch {
+    return 'unknown'
+  }
+}
+
+function isPythonInstalled(): { installed: boolean; cmd: string } {
+  for (const cmd of ['python3', 'python']) {
+    try {
+      execSync(`${cmd} --version`, { stdio: 'pipe', timeout: 5000 })
+      return { installed: true, cmd }
+    } catch {
+      // try next
+    }
+  }
+  return { installed: false, cmd: 'python3' }
+}
+
+function getRunningPid(): number | null {
+  const pidPath = getPidFilePath()
+  if (!existsSync(pidPath)) return null
+
+  try {
+    const pid = parseInt(readFileSync(pidPath, 'utf-8').trim(), 10)
+    if (isNaN(pid)) {
+      unlinkSync(pidPath)
+      return null
+    }
+    // Signal 0 tests if process exists without killing it
+    process.kill(pid, 0)
+    return pid
+  } catch {
+    // Process not running, clean up stale PID file
+    try { unlinkSync(pidPath) } catch {}
+    return null
+  }
+}
+
+function isChromaReachable(): boolean {
+  try {
+    execSync(`curl -sf http://localhost:${DEFAULT_PORT}/api/v1/heartbeat`, {
+      stdio: 'pipe',
+      timeout: 3000
+    })
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+// ── Subcommands ───────────────────────────────────────────
+
+async function chromaStart(): Promise<void> {
+  console.log()
+  console.log(heading('Starting ChromaDB Server'))
+  console.log()
+
+  // Check if already running
+  const existingPid = getRunningPid()
+  if (existingPid) {
+    console.log(warningText(`ChromaDB is already running (PID: ${existingPid})`))
+    console.log()
+    return
+  }
+
+  if (isChromaReachable()) {
+    console.log(warningText('A ChromaDB server is already running on port ' + DEFAULT_PORT))
+    console.log()
+    return
+  }
+
+  // Check if chroma CLI is installed
+  if (!isChromaCliInstalled()) {
+    console.log(errorText('ChromaDB CLI is not installed.'))
+    console.log()
+    console.log(dimText('Install it with:'))
+    console.log(`  ${theme.primary('pip install chromadb')}`)
+    console.log()
+    console.log(dimText('Or run:'))
+    console.log(`  ${theme.primary('claude-brain chroma install')}`)
+    console.log()
+    process.exit(1)
+  }
+
+  const dataPath = getChromaDataPath()
+
+  console.log(dimText(`Data path: ${dataPath}`))
+  console.log(dimText(`Port: ${DEFAULT_PORT}`))
+  console.log()
+
+  // Start ChromaDB server in background
+  const child = spawn('chroma', ['run', '--path', dataPath, '--port', DEFAULT_PORT], {
+    detached: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: { ...process.env }
+  })
+
+  const pid = child.pid
+  if (!pid) {
+    console.log(errorText('Failed to start ChromaDB server — no PID returned.'))
+    console.log()
+    process.exit(1)
+  }
+
+  // Detach the child process so it runs independently
+  child.unref()
+
+  // Save PID file
+  writeFileSync(getPidFilePath(), String(pid), 'utf-8')
+
+  // Capture early output for error detection
+  let startupOutput = ''
+  child.stderr?.on('data', (chunk: Buffer) => {
+    startupOutput += chunk.toString()
+  })
+  child.stdout?.on('data', (chunk: Buffer) => {
+    startupOutput += chunk.toString()
+  })
+
+  // Wait up to 15 seconds for server to become reachable
+  let ready = false
+  for (let i = 0; i < 30; i++) {
+    await sleep(500)
+    if (isChromaReachable()) {
+      ready = true
+      break
+    }
+    // Check if process exited early
+    try {
+      process.kill(pid, 0)
+    } catch {
+      break
+    }
+  }
+
+  if (ready) {
+    console.log(successText(`ChromaDB server started (PID: ${pid})`))
+    console.log()
+    console.log(dimText('The server is running in the background.'))
+    console.log(dimText('Stop it with: ') + theme.primary('claude-brain chroma stop'))
+  } else {
+    // Check if process is still alive
+    let alive = false
+    try {
+      process.kill(pid, 0)
+      alive = true
+    } catch {}
+
+    if (alive) {
+      console.log(warningText('ChromaDB server started but not yet responding.'))
+      console.log(dimText(`PID: ${pid} — it may still be initializing.`))
+      console.log(dimText('Check with: ') + theme.primary('claude-brain chroma status'))
+    } else {
+      console.log(errorText('ChromaDB server failed to start.'))
+      if (startupOutput) {
+        console.log(dimText('Output:'))
+        console.log(dimText(startupOutput.slice(0, 500)))
+      }
+      try { unlinkSync(getPidFilePath()) } catch {}
+      process.exit(1)
+    }
+  }
+  console.log()
+}
+
+async function chromaStop(): Promise<void> {
+  console.log()
+  console.log(heading('Stopping ChromaDB Server'))
+  console.log()
+
+  const pid = getRunningPid()
+  if (!pid) {
+    if (isChromaReachable()) {
+      console.log(warningText('A ChromaDB server is running on port ' + DEFAULT_PORT + ' but was not started by claude-brain.'))
+      console.log(dimText('Kill it manually if needed.'))
+    } else {
+      console.log(dimText('No ChromaDB server is currently running.'))
+    }
+    console.log()
+    return
+  }
+
+  try {
+    process.kill(pid, 'SIGTERM')
+
+    // Wait up to 5 seconds for graceful shutdown
+    for (let i = 0; i < 10; i++) {
+      await sleep(500)
+      try {
+        process.kill(pid, 0)
+      } catch {
+        // Process exited
+        break
+      }
+    }
+
+    // Force kill if still running
+    try {
+      process.kill(pid, 0)
+      // Still alive, force kill
+      process.kill(pid, 'SIGKILL')
+    } catch {
+      // Already dead, good
+    }
+
+    try { unlinkSync(getPidFilePath()) } catch {}
+
+    console.log(successText(`ChromaDB server stopped (PID: ${pid})`))
+  } catch (error) {
+    console.log(errorText(`Failed to stop ChromaDB: ${error instanceof Error ? error.message : String(error)}`))
+    try { unlinkSync(getPidFilePath()) } catch {}
+  }
+  console.log()
+}
+
+async function chromaStatus(): Promise<void> {
+  console.log()
+
+  const pid = getRunningPid()
+  const reachable = isChromaReachable()
+  const installed = isChromaCliInstalled()
+  const version = installed ? getChromaVersion() : 'N/A'
+  const dataPath = getChromaDataPath()
+  const dataExists = existsSync(dataPath)
+
+  const items: Record<string, string> = {
+    'Installed': installed ? `Yes (${version})` : 'No',
+    'Server': reachable ? `Running (port ${DEFAULT_PORT})` : 'Not running',
+    'Managed PID': pid ? String(pid) : 'None',
+    'Data Path': dataPath,
+    'Data Exists': dataExists ? 'Yes' : 'No',
+  }
+
+  console.log(infoPanel('ChromaDB Status', items))
+
+  if (!installed) {
+    console.log()
+    console.log(warningText('ChromaDB is not installed.'))
+    console.log(dimText('Install with: ') + theme.primary('claude-brain chroma install'))
+  } else if (!reachable) {
+    console.log()
+    console.log(dimText('Start the server with: ') + theme.primary('claude-brain chroma start'))
+  }
+  console.log()
+}
+
+async function chromaInstall(): Promise<void> {
+  console.log()
+  console.log(heading('Installing ChromaDB'))
+  console.log()
+
+  if (isChromaCliInstalled()) {
+    const version = getChromaVersion()
+    console.log(successText(`ChromaDB is already installed (${version}).`))
+    console.log()
+    return
+  }
+
+  const python = isPythonInstalled()
+  if (!python.installed) {
+    console.log(errorText('Python 3 is required to install ChromaDB.'))
+    console.log()
+    console.log(dimText('Install Python 3 first:'))
+    console.log(`  ${theme.primary('macOS:')}   brew install python3`)
+    console.log(`  ${theme.primary('Ubuntu:')}  sudo apt install python3 python3-pip`)
+    console.log(`  ${theme.primary('Windows:')} https://python.org/downloads`)
+    console.log()
+    process.exit(1)
+  }
+
+  console.log(dimText(`Found ${python.cmd}. Installing chromadb via pip...`))
+  console.log()
+
+  const pipCommands = python.cmd === 'python3'
+    ? ['pip3 install chromadb', 'python3 -m pip install chromadb']
+    : ['pip install chromadb', 'python -m pip install chromadb']
+
+  let installed = false
+  for (const cmd of pipCommands) {
+    try {
+      execSync(cmd, { stdio: 'inherit', timeout: 300_000 })
+      installed = true
+      break
+    } catch {
+      // Try next command
+    }
+  }
+
+  console.log()
+  if (installed) {
+    console.log(successText('ChromaDB installed successfully!'))
+    console.log()
+    console.log(dimText('Start the server with: ') + theme.primary('claude-brain chroma start'))
+  } else {
+    console.log(errorText('Failed to install ChromaDB.'))
+    console.log(dimText('Try installing manually:'))
+    console.log(`  ${theme.primary('pip install chromadb')}`)
+    process.exit(1)
+  }
+  console.log()
+}
+
+// ── Help ──────────────────────────────────────────────────
+
+function printChromaHelp(): void {
+  console.log()
+  console.log(heading('ChromaDB Management'))
+  console.log()
+  console.log(dimText('ChromaDB provides vector storage for semantic search,'))
+  console.log(dimText('knowledge graph, and advanced intelligence features.'))
+  console.log()
+
+  const commands = [
+    ['start', 'Start ChromaDB server in background'],
+    ['stop', 'Stop the running ChromaDB server'],
+    ['status', 'Show ChromaDB server status'],
+    ['install', 'Install ChromaDB (requires Python 3)'],
+  ]
+
+  const cmdLines = commands
+    .map(([cmd, desc]) => `  ${theme.primary(cmd!.padEnd(12))} ${dimText(desc!)}`)
+    .join('\n')
+
+  console.log(theme.bold('Commands:'))
+  console.log(cmdLines)
+  console.log()
+
+  console.log(theme.bold('Usage:'))
+  console.log(`  ${dimText('claude-brain chroma install')}   ${dimText('Install ChromaDB')}`)
+  console.log(`  ${dimText('claude-brain chroma start')}     ${dimText('Start the server')}`)
+  console.log(`  ${dimText('claude-brain chroma status')}    ${dimText('Check if running')}`)
+  console.log(`  ${dimText('claude-brain chroma stop')}      ${dimText('Stop the server')}`)
+  console.log()
+}
+
+// ── Entry Point ───────────────────────────────────────────
+
+export async function runChroma(): Promise<void> {
+  const subcommand = process.argv[3] || 'help'
+
+  switch (subcommand) {
+    case 'start':
+      await chromaStart()
+      break
+    case 'stop':
+      await chromaStop()
+      break
+    case 'status':
+      await chromaStatus()
+      break
+    case 'install':
+      await chromaInstall()
+      break
+    case 'help':
+    case '--help':
+    case '-h':
+      printChromaHelp()
+      break
+    default:
+      console.log()
+      console.log(errorText(`Unknown subcommand: ${subcommand}`))
+      printChromaHelp()
+      process.exit(1)
+  }
+}

package/src/config/defaults.ts

@@ -3,7 +3,7 @@ import type { PartialConfig } from './schema'
 /** Default configuration values for Claude Brain */
 export const defaultConfig: PartialConfig = {
   serverName: 'claude-brain',
-  serverVersion: '0.3.7',
+  serverVersion: '0.4.1',
   logLevel: 'info',
   logFilePath: './logs/claude-brain.log',
   dbPath: './data/memory.db',

package/src/config/schema.ts

@@ -196,7 +196,7 @@ export const ConfigSchema = z.object({
   serverName: z.string().default('claude-brain'),
 
   /** Server version in semver format */
-  serverVersion: z.string().regex(/^\d+\.\d+\.\d+$/, 'Version must be semver format').default('0.3.7'),
+  serverVersion: z.string().regex(/^\d+\.\d+\.\d+$/, 'Version must be semver format').default('0.4.1'),
 
   /** Logging level */
   logLevel: LogLevelSchema.default('info'),

package/src/context/standards-manager.ts

@@ -248,6 +248,26 @@ export class StandardsManager {
             'Ignoring error handling',
             'Deep nesting'
           ]
+        },
+        {
+          language: 'JavaScript',
+          version: 'ES2022+',
+          style: 'standard',
+          linting: {},
+          conventions: [
+            'Use strict mode',
+            'Prefer const over let',
+            'Use async/await over promises',
+            'Use optional chaining and nullish coalescing',
+            'Add JSDoc comments for public APIs'
+          ],
+          antiPatterns: [
+            'Using var',
+            'Callback hell',
+            'Ignoring error handling',
+            'Deep nesting',
+            'Mutating function arguments'
+          ]
         }
       ],
       frameworks: [],

package/src/memory/chroma/client.ts

@@ -36,12 +36,12 @@ export class ChromaClientManager {
           break
 
         case 'client-server':
-          if (!this.config.host || !this.config.port) {
-            throw new Error('Host and port required for client-server mode')
+          if (!this.config.host) {
+            throw new Error('Host required for client-server mode')
           }
           this.client = new ChromaClient({
             host: this.config.host,
-            port: this.config.port,
+            port: this.config.port || 8000,
             ...authConfig
           })
           break
@@ -82,8 +82,9 @@ export class ChromaClientManager {
         this.isConnected = true
         this.logger.info('ChromaDB client initialized successfully')
       } catch (heartbeatError) {
-        this.logger.warn({ error: heartbeatError }, 'ChromaDB heartbeat failed, connection may not be fully established')
-        this.isConnected = true
+        this.isConnected = false
+        this.logger.warn({ error: heartbeatError }, 'ChromaDB heartbeat failed')
+        throw new Error(`ChromaDB server unreachable: ${heartbeatError instanceof Error ? heartbeatError.message : String(heartbeatError)}`)
       }
 
     } catch (error) {

package/src/memory/chroma/config.ts

@@ -35,7 +35,18 @@ export function getChromaConfigFromEnv(): Partial<ChromaConfig> {
 
   if (process.env.CHROMA_HOST) {
     config.host = process.env.CHROMA_HOST
-    config.mode = 'cloud'
+    // Only default to cloud if CHROMA_MODE isn't explicitly set
+    if (!process.env.CHROMA_MODE) {
+      config.mode = 'cloud'
+    }
+  }
+
+  if (process.env.CHROMA_MODE) {
+    config.mode = process.env.CHROMA_MODE as any
+  }
+
+  if (process.env.CHROMA_PORT) {
+    config.port = parseInt(process.env.CHROMA_PORT, 10)
   }
 
   if (process.env.CHROMA_EMBEDDING_PROVIDER) {