mdcontext 0.0.1 → 0.2.0

package/src/search/wink-bm25.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Type declarations for wink-bm25-text-search
+ */
+
+declare module 'wink-bm25-text-search' {
+  interface BM25Config {
+    fldWeights?: Record<string, number>
+    bm25Params?: {
+      k1?: number
+      b?: number
+    }
+    ovFldNames?: string[]
+  }
+
+  type PrepTask = (text: string) => string[]
+
+  interface BM25Engine {
+    defineConfig(config: BM25Config): void
+    definePrepTasks(tasks: PrepTask[]): void
+    addDoc(doc: Record<string, string>, id: number): void
+    consolidate(): void
+    search(query: string, limit?: number): [number, number][]
+    exportJSON(): string
+    importJSON(json: string): void
+    reset(): void
+  }
+
+  function bm25(): BM25Engine
+  export default bm25
+}

package/src/summarization/cli-providers/claude.ts

@@ -0,0 +1,202 @@
+/**
+ * Claude CLI Summarizer
+ *
+ * Uses Claude Code CLI for AI summarization.
+ * FREE for users with Claude Code subscriptions.
+ *
+ * SECURITY: Uses spawn() with argument arrays - NEVER exec() with string interpolation.
+ */
+
+import { spawn } from 'node:child_process'
+import type {
+  StreamingSummarizer,
+  StreamOptions,
+  SummaryResult,
+} from '../types.js'
+import { SummarizationError as SummarizationErrorClass } from '../types.js'
+
+/**
+ * Claude CLI provider for summarization.
+ *
+ * Uses the `claude` CLI tool in non-interactive mode with text output.
+ * Requires Claude Code installation and authentication.
+ *
+ * @security Uses spawn() with argument arrays to prevent shell injection.
+ *           User input is passed as array elements, never interpolated.
+ *
+ * @cost Free (uses existing Claude subscription)
+ *
+ * @example
+ * ```typescript
+ * const summarizer = new ClaudeCLISummarizer()
+ *
+ * // Check availability
+ * if (await summarizer.isAvailable()) {
+ *   const result = await summarizer.summarize(searchResults, prompt)
+ *   console.log(result.summary)
+ *   // result.estimatedCost is always 0 (free)
+ * }
+ *
+ * // Streaming output
+ * await summarizer.summarizeStream(searchResults, prompt, {
+ *   onChunk: (chunk) => process.stdout.write(chunk),
+ *   onComplete: (result) => console.log(`Done in ${result.durationMs}ms`),
+ * })
+ * ```
+ */
+export class ClaudeCLISummarizer implements StreamingSummarizer {
+  private readonly command = 'claude'
+
+  async summarize(input: string, prompt: string): Promise<SummaryResult> {
+    const startTime = Date.now()
+    const fullPrompt = `${prompt}\n\n${input}`
+
+    return new Promise((resolve, reject) => {
+      // SECURITY: spawn() with argument array - safe from shell injection
+      const proc = spawn(
+        this.command,
+        ['-p', fullPrompt, '--output-format', 'text'],
+        {
+          stdio: ['ignore', 'pipe', 'pipe'],
+        },
+      )
+
+      let stdout = ''
+      let stderr = ''
+
+      proc.stdout.on('data', (data: Buffer) => {
+        stdout += data.toString()
+      })
+
+      proc.stderr.on('data', (data: Buffer) => {
+        stderr += data.toString()
+      })
+
+      proc.on('close', (code: number | null) => {
+        const durationMs = Date.now() - startTime
+
+        if (code !== 0) {
+          reject(
+            new SummarizationErrorClass(
+              `Claude CLI exited with code ${code}: ${stderr}`,
+              'CLI_EXECUTION_FAILED',
+              'claude',
+            ),
+          )
+          return
+        }
+
+        resolve({
+          summary: stdout.trim(),
+          provider: 'claude',
+          mode: 'cli',
+          estimatedCost: 0,
+          durationMs,
+        })
+      })
+
+      proc.on('error', (error: Error) => {
+        reject(
+          new SummarizationErrorClass(
+            `Failed to spawn Claude CLI: ${error.message}`,
+            'CLI_EXECUTION_FAILED',
+            'claude',
+            error,
+          ),
+        )
+      })
+    })
+  }
+
+  async summarizeStream(
+    input: string,
+    prompt: string,
+    options: StreamOptions,
+  ): Promise<void> {
+    const startTime = Date.now()
+    const fullPrompt = `${prompt}\n\n${input}`
+
+    return new Promise((resolve, reject) => {
+      // SECURITY: spawn() with argument array - safe from shell injection
+      const proc = spawn(
+        this.command,
+        ['-p', fullPrompt, '--output-format', 'text'],
+        {
+          stdio: ['ignore', 'pipe', 'pipe'],
+        },
+      )
+
+      let fullOutput = ''
+      let stderr = ''
+
+      proc.stdout.on('data', (data: Buffer) => {
+        const chunk = data.toString()
+        fullOutput += chunk
+        options.onChunk(chunk)
+      })
+
+      proc.stderr.on('data', (data: Buffer) => {
+        stderr += data.toString()
+      })
+
+      proc.on('close', (code: number | null) => {
+        const durationMs = Date.now() - startTime
+
+        if (code !== 0) {
+          const error = new SummarizationErrorClass(
+            `Claude CLI exited with code ${code}: ${stderr}`,
+            'CLI_EXECUTION_FAILED',
+            'claude',
+          )
+          options.onError?.(error)
+          reject(error)
+          return
+        }
+
+        const result: SummaryResult = {
+          summary: fullOutput.trim(),
+          provider: 'claude',
+          mode: 'cli',
+          estimatedCost: 0,
+          durationMs,
+        }
+
+        options.onComplete?.(result)
+        resolve()
+      })
+
+      proc.on('error', (error: Error) => {
+        const sumError = new SummarizationErrorClass(
+          `Failed to spawn Claude CLI: ${error.message}`,
+          'CLI_EXECUTION_FAILED',
+          'claude',
+          error,
+        )
+        options.onError?.(sumError)
+        reject(sumError)
+      })
+    })
+  }
+
+  estimateCost(_inputTokens: number): number {
+    // CLI providers are free with subscription
+    return 0
+  }
+
+  async isAvailable(): Promise<boolean> {
+    return new Promise((resolve) => {
+      const checkCommand = process.platform === 'win32' ? 'where' : 'which'
+      const proc = spawn(checkCommand, [this.command], {
+        stdio: ['ignore', 'ignore', 'ignore'],
+      })
+
+      proc.on('close', (code) => {
+        resolve(code === 0)
+      })
+
+      proc.on('error', () => {
+        resolve(false)
+      })
+    })
+  }
+}

package/src/summarization/cli-providers/detection.test.ts

@@ -0,0 +1,273 @@
+/**
+ * Tests for CLI Provider Detection Module
+ */
+
+import { type ChildProcess, spawn } from 'node:child_process'
+import { EventEmitter } from 'node:events'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { CLIProviderName } from '../types.js'
+import {
+  detectInstalledCLIs,
+  getCLIInfo,
+  isCLIInstalled,
+  KNOWN_CLIS,
+} from './detection.js'
+
+vi.mock('node:child_process', () => ({
+  spawn: vi.fn(),
+}))
+
+const mockSpawn = vi.mocked(spawn)
+
+const createMockProcess = (exitCode: number | null, emitError = false) => {
+  const proc = new EventEmitter() as ChildProcess
+  setTimeout(() => {
+    if (emitError) {
+      proc.emit('error', new Error('spawn ENOENT'))
+    } else {
+      proc.emit('close', exitCode)
+    }
+  }, 0)
+  return proc
+}
+
+describe('KNOWN_CLIS', () => {
+  const expectedProviders: CLIProviderName[] = [
+    'claude',
+    'opencode',
+    'copilot',
+    'aider',
+    'cline',
+    'amp',
+  ]
+
+  it('should contain all expected CLI providers', () => {
+    const names = KNOWN_CLIS.map((cli) => cli.name)
+    for (const provider of expectedProviders) {
+      expect(names).toContain(provider)
+    }
+  })
+
+  it('should have required fields for each CLI', () => {
+    for (const cli of KNOWN_CLIS) {
+      expect(cli).toHaveProperty('name')
+      expect(cli).toHaveProperty('command')
+      expect(cli).toHaveProperty('displayName')
+      expect(cli).toHaveProperty('args')
+      expect(cli).toHaveProperty('useStdin')
+
+      expect(typeof cli.name).toBe('string')
+      expect(typeof cli.command).toBe('string')
+      expect(typeof cli.displayName).toBe('string')
+      expect(Array.isArray(cli.args)).toBe(true)
+      expect(typeof cli.useStdin).toBe('boolean')
+    }
+  })
+
+  describe('individual CLI configurations', () => {
+    it('should have correct claude configuration', () => {
+      const claude = KNOWN_CLIS.find((cli) => cli.name === 'claude')
+      expect(claude).toBeDefined()
+      expect(claude!.command).toBe('claude')
+      expect(claude!.displayName).toBe('Claude Code')
+      expect(claude!.args).toContain('-p')
+      expect(claude!.useStdin).toBe(false)
+    })
+
+    it('should have correct opencode configuration', () => {
+      const opencode = KNOWN_CLIS.find((cli) => cli.name === 'opencode')
+      expect(opencode).toBeDefined()
+      expect(opencode!.command).toBe('opencode')
+      expect(opencode!.displayName).toBe('OpenCode')
+      expect(opencode!.useStdin).toBe(true)
+    })
+
+    it('should have correct copilot configuration', () => {
+      const copilot = KNOWN_CLIS.find((cli) => cli.name === 'copilot')
+      expect(copilot).toBeDefined()
+      expect(copilot!.command).toBe('gh')
+      expect(copilot!.displayName).toBe('GitHub Copilot CLI')
+      expect(copilot!.args).toContain('copilot')
+      expect(copilot!.useStdin).toBe(true)
+    })
+
+    it('should have correct aider configuration', () => {
+      const aider = KNOWN_CLIS.find((cli) => cli.name === 'aider')
+      expect(aider).toBeDefined()
+      expect(aider!.command).toBe('aider')
+      expect(aider!.displayName).toBe('Aider')
+      expect(aider!.useStdin).toBe(false)
+    })
+
+    it('should have correct cline configuration', () => {
+      const cline = KNOWN_CLIS.find((cli) => cli.name === 'cline')
+      expect(cline).toBeDefined()
+      expect(cline!.command).toBe('cline')
+      expect(cline!.displayName).toBe('Cline')
+      expect(cline!.useStdin).toBe(false)
+    })
+
+    it('should have correct amp configuration', () => {
+      const amp = KNOWN_CLIS.find((cli) => cli.name === 'amp')
+      expect(amp).toBeDefined()
+      expect(amp!.command).toBe('amp')
+      expect(amp!.displayName).toBe('Amp')
+      expect(amp!.useStdin).toBe(false)
+    })
+  })
+})
+
+describe('getCLIInfo', () => {
+  it('should return correct info for known providers', () => {
+    const claude = getCLIInfo('claude')
+    expect(claude).toBeDefined()
+    expect(claude!.name).toBe('claude')
+    expect(claude!.command).toBe('claude')
+
+    const copilot = getCLIInfo('copilot')
+    expect(copilot).toBeDefined()
+    expect(copilot!.name).toBe('copilot')
+    expect(copilot!.command).toBe('gh')
+  })
+
+  it('should return undefined for unknown provider', () => {
+    const unknown = getCLIInfo('unknown' as CLIProviderName)
+    expect(unknown).toBeUndefined()
+  })
+
+  it('should return all fields for a CLI', () => {
+    const cli = getCLIInfo('claude')
+    expect(cli).toMatchObject({
+      name: 'claude',
+      command: 'claude',
+      displayName: 'Claude Code',
+      args: expect.any(Array),
+      useStdin: false,
+    })
+  })
+})
+
+describe('isCLIInstalled', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('should return true when CLI exists (exit code 0)', async () => {
+    mockSpawn.mockReturnValue(createMockProcess(0))
+
+    const result = await isCLIInstalled('claude')
+
+    expect(result).toBe(true)
+    expect(mockSpawn).toHaveBeenCalledWith(
+      expect.stringMatching(/^(which|where)$/),
+      ['claude'],
+      { stdio: ['ignore', 'pipe', 'ignore'] },
+    )
+  })
+
+  it('should return false when CLI does not exist (exit code 1)', async () => {
+    mockSpawn.mockReturnValue(createMockProcess(1))
+
+    const result = await isCLIInstalled('claude')
+
+    expect(result).toBe(false)
+  })
+
+  it('should return false when spawn emits an error', async () => {
+    mockSpawn.mockReturnValue(createMockProcess(null, true))
+
+    const result = await isCLIInstalled('claude')
+
+    expect(result).toBe(false)
+  })
+
+  it('should return false for unknown provider', async () => {
+    const result = await isCLIInstalled('unknown' as CLIProviderName)
+
+    expect(result).toBe(false)
+    expect(mockSpawn).not.toHaveBeenCalled()
+  })
+
+  it('should check the correct command for copilot (gh)', async () => {
+    mockSpawn.mockReturnValue(createMockProcess(0))
+
+    await isCLIInstalled('copilot')
+
+    expect(mockSpawn).toHaveBeenCalledWith(
+      expect.stringMatching(/^(which|where)$/),
+      ['gh'],
+      expect.any(Object),
+    )
+  })
+})
+
+describe('detectInstalledCLIs', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('should return all CLIs when all are installed', async () => {
+    mockSpawn.mockReturnValue(createMockProcess(0))
+
+    const result = await detectInstalledCLIs()
+
+    expect(result.length).toBe(KNOWN_CLIS.length)
+    expect(result.map((cli) => cli.name)).toEqual(
+      expect.arrayContaining([
+        'claude',
+        'opencode',
+        'copilot',
+        'aider',
+        'cline',
+        'amp',
+      ]),
+    )
+  })
+
+  it('should return empty array when no CLIs are installed', async () => {
+    mockSpawn.mockReturnValue(createMockProcess(1))
+
+    const result = await detectInstalledCLIs()
+
+    expect(result).toEqual([])
+  })
+
+  it('should return only installed CLIs', async () => {
+    const installedCommands = new Set(['claude', 'gh'])
+    mockSpawn.mockImplementation((_cmd, args) => {
+      const command = args[0] as string
+      const isInstalled = installedCommands.has(command)
+      return createMockProcess(isInstalled ? 0 : 1)
+    })
+
+    const result = await detectInstalledCLIs()
+
+    expect(result.length).toBe(2)
+    expect(result.map((cli) => cli.name)).toContain('claude')
+    expect(result.map((cli) => cli.name)).toContain('copilot')
+  })
+
+  it('should handle errors gracefully', async () => {
+    mockSpawn.mockReturnValue(createMockProcess(null, true))
+
+    const result = await detectInstalledCLIs()
+
+    expect(result).toEqual([])
+  })
+
+  it('should check all known CLIs', async () => {
+    mockSpawn.mockReturnValue(createMockProcess(0))
+
+    await detectInstalledCLIs()
+
+    expect(mockSpawn).toHaveBeenCalledTimes(KNOWN_CLIS.length)
+  })
+})

package/src/summarization/cli-providers/detection.ts

@@ -0,0 +1,118 @@
+/**
+ * CLI Provider Detection
+ *
+ * Detects installed CLI tools that can be used for AI summarization.
+ * Uses spawn() with argument arrays for security - NEVER exec() with string interpolation.
+ */
+
+import { spawn } from 'node:child_process'
+import type { CLIInfo, CLIProviderName } from '../types.js'
+
+/**
+ * Known CLI tools with their configuration.
+ *
+ * SECURITY: All CLI invocations use spawn() with argument arrays.
+ * The args array is used directly, never interpolated into strings.
+ */
+export const KNOWN_CLIS: readonly CLIInfo[] = [
+  {
+    name: 'claude',
+    command: 'claude',
+    displayName: 'Claude Code',
+    args: ['-p', '--output-format', 'text'],
+    useStdin: false, // Uses -p flag for prompt, not stdin
+  },
+  {
+    name: 'opencode',
+    command: 'opencode',
+    displayName: 'OpenCode',
+    args: ['run', '--format', 'text'],
+    useStdin: true,
+  },
+  {
+    name: 'copilot',
+    command: 'gh',
+    displayName: 'GitHub Copilot CLI',
+    args: ['copilot', 'explain'],
+    useStdin: true,
+  },
+  {
+    name: 'aider',
+    command: 'aider',
+    displayName: 'Aider',
+    args: ['--message'],
+    useStdin: false,
+  },
+  {
+    name: 'cline',
+    command: 'cline',
+    displayName: 'Cline',
+    args: ['--prompt'],
+    useStdin: false,
+  },
+  {
+    name: 'amp',
+    command: 'amp',
+    displayName: 'Amp',
+    args: ['--prompt'],
+    useStdin: false,
+  },
+] as const
+
+/**
+ * Check if a command exists on the system.
+ *
+ * SECURITY: Uses spawn() with argument array, not exec() with string interpolation.
+ */
+const commandExists = (command: string): Promise<boolean> => {
+  return new Promise((resolve) => {
+    // Use 'which' on Unix, 'where' on Windows
+    const checkCommand = process.platform === 'win32' ? 'where' : 'which'
+
+    const proc = spawn(checkCommand, [command], {
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+
+    proc.on('close', (code) => {
+      resolve(code === 0)
+    })
+
+    proc.on('error', () => {
+      resolve(false)
+    })
+  })
+}
+
+/**
+ * Detect all installed CLI tools that can be used for summarization.
+ *
+ * @returns Array of CLIInfo for installed tools
+ */
+export const detectInstalledCLIs = async (): Promise<CLIInfo[]> => {
+  const results = await Promise.all(
+    KNOWN_CLIS.map(async (cli) => {
+      const exists = await commandExists(cli.command)
+      return exists ? cli : null
+    }),
+  )
+
+  return results.filter((cli): cli is CLIInfo => cli !== null)
+}
+
+/**
+ * Get CLI info by name.
+ */
+export const getCLIInfo = (name: CLIProviderName): CLIInfo | undefined => {
+  return KNOWN_CLIS.find((cli) => cli.name === name)
+}
+
+/**
+ * Check if a specific CLI is installed.
+ */
+export const isCLIInstalled = async (
+  name: CLIProviderName,
+): Promise<boolean> => {
+  const cli = getCLIInfo(name)
+  if (!cli) return false
+  return commandExists(cli.command)
+}

package/src/summarization/cli-providers/index.ts

@@ -0,0 +1,8 @@
+/**
+ * CLI Providers Module
+ *
+ * Exports all CLI-based summarizers and detection utilities.
+ */
+
+export * from './claude.js'
+export * from './detection.js'