mdcontext 0.1.0 → 0.2.0

package/src/cli/flag-schemas.ts

@@ -83,6 +83,43 @@ export const indexSchema: CommandSchema = {
       type: 'boolean',
       description: 'Skip semantic search prompt',
     },
+    {
+      name: 'exclude',
+      type: 'string',
+      alias: 'x',
+      description: 'Additional patterns to exclude (comma-separated)',
+    },
+    {
+      name: 'no-gitignore',
+      type: 'boolean',
+      description: 'Ignore .gitignore file',
+    },
+    {
+      name: 'provider',
+      type: 'string',
+      description:
+        'Embedding provider: openai, ollama, lm-studio, openrouter, voyage',
+    },
+    {
+      name: 'provider-base-url',
+      type: 'string',
+      description: 'Custom API base URL for the provider',
+    },
+    {
+      name: 'provider-model',
+      type: 'string',
+      description: 'Model name (e.g., nomic-embed-text for Ollama)',
+    },
+    {
+      name: 'hnsw-m',
+      type: 'string',
+      description: 'HNSW M parameter',
+    },
+    {
+      name: 'hnsw-ef-construction',
+      type: 'string',
+      description: 'HNSW efConstruction parameter',
+    },
     {
       name: 'watch',
       type: 'boolean',
@@ -141,6 +178,28 @@ export const searchSchema: CommandSchema = {
       alias: 'A',
       description: 'Lines of context after matches (like grep -A)',
     },
+    {
+      name: 'fuzzy',
+      type: 'boolean',
+      alias: 'f',
+      description: 'Enable fuzzy matching for typo tolerance',
+    },
+    {
+      name: 'stem',
+      type: 'boolean',
+      description: 'Enable word stemming (fail matches failure, failed)',
+    },
+    {
+      name: 'fuzzy-distance',
+      type: 'string',
+      description: 'Max edit distance for fuzzy matching (default: 2)',
+    },
+    {
+      name: 'refine',
+      type: 'string',
+      description:
+        'Additional filter to narrow results (can be used multiple times)',
+    },
     jsonFlag,
     prettyFlag,
   ],
@@ -168,6 +227,13 @@ export const contextSchema: CommandSchema = {
       type: 'boolean',
       description: 'Exclude nested subsections when filtering',
     },
+    {
+      name: 'exclude',
+      type: 'string',
+      alias: 'x',
+      description:
+        'Exclude sections matching pattern (can be used multiple times)',
+    },
     jsonFlag,
     prettyFlag,
   ],

package/src/cli/help.ts

@@ -32,6 +32,10 @@ export const helpContent: Record<string, CommandHelp> = {
       'mdcontext index --watch            # Watch for file changes',
       'mdcontext index --embed --watch    # Full setup with live updates',
       'mdcontext index --force            # Rebuild from scratch',
+      '',
+      '# Alternative embedding providers:',
+      'mdcontext index --embed --provider ollama --provider-model nomic-embed-text',
+      'mdcontext index --embed --provider openrouter',
     ],
     options: [
       {
@@ -42,6 +46,23 @@ export const helpContent: Record<string, CommandHelp> = {
         name: '--no-embed',
         description: 'Skip the prompt to enable semantic search',
       },
+      {
+        name: '--provider <name>',
+        description:
+          'Embedding provider: openai, ollama, lm-studio, openrouter, voyage',
+      },
+      {
+        name: '--provider-model <model>',
+        description: 'Model name (e.g., nomic-embed-text for Ollama)',
+      },
+      {
+        name: '--provider-base-url <url>',
+        description: 'Custom API base URL for the provider',
+      },
+      {
+        name: '-t, --timeout <ms>',
+        description: 'Embedding API timeout in milliseconds (default: 30000)',
+      },
       {
         name: '-w, --watch',
         description: 'Watch for changes and re-index automatically',
@@ -52,7 +73,8 @@ export const helpContent: Record<string, CommandHelp> = {
     ],
     notes: [
       'After indexing, prompts to enable semantic search (use --no-embed to skip).',
-      'Embedding requires OPENAI_API_KEY environment variable.',
+      'Providers: openai (default), ollama (free/local), lm-studio, openrouter, voyage.',
+      'Set API keys: OPENAI_API_KEY, OPENROUTER_API_KEY, or use local providers.',
       'Index is stored in .mdcontext/ directory.',
     ],
   },
@@ -76,6 +98,21 @@ export const helpContent: Record<string, CommandHelp> = {
       '# Context lines (like grep):',
       'mdcontext search "checkpoint" -C 3         # 3 lines before AND after',
       'mdcontext search "error" -B 2 -A 5         # 2 before, 5 after',
+      '',
+      '# Quality modes (speed vs recall tradeoff):',
+      'mdcontext search "auth" --quality fast       # Faster, slight recall reduction',
+      'mdcontext search "auth" -q thorough          # Best recall, ~30% slower',
+      '',
+      '# Re-ranking for precision:',
+      'mdcontext search "auth" --rerank           # Re-rank with cross-encoder',
+      '',
+      '# HyDE for complex queries:',
+      'mdcontext search "how to implement auth" --hyde   # Expands query semantically',
+      '',
+      '# AI summarization:',
+      'mdcontext search "auth" --summarize        # Get AI summary of results',
+      'mdcontext search "error" -s --yes          # Skip cost confirmation',
+      'mdcontext search "config" -s --stream      # Stream summary output',
     ],
     options: [
       {
@@ -88,7 +125,7 @@ export const helpContent: Record<string, CommandHelp> = {
       },
       {
         name: '-m, --mode <mode>',
-        description: 'Force search mode: semantic or keyword',
+        description: 'Force search mode: semantic, keyword, or hybrid',
       },
       {
         name: '-n, --limit <n>',
@@ -109,10 +146,50 @@ export const helpContent: Record<string, CommandHelp> = {
       {
         name: '--threshold <n>',
         description:
-          'Similarity threshold 0-1 for semantic search (default: 0.5)',
+          'Similarity threshold 0-1 for semantic search (default: 0.35)',
+      },
+      {
+        name: '--provider <name>',
+        description: 'Embedding provider for semantic search',
+      },
+      {
+        name: '--timeout <ms>',
+        description: 'Embedding API timeout in milliseconds (default: 30000)',
+      },
+      {
+        name: '-r, --rerank',
+        description:
+          'Re-rank results with cross-encoder for better precision. Downloads ~90MB model on first use.',
+      },
+      {
+        name: '--rerank-init',
+        description:
+          'Pre-download cross-encoder model (~90MB) before first search to avoid latency.',
+      },
+      {
+        name: '-q, --quality <mode>',
+        description:
+          'Search quality: fast (quicker), balanced (default), thorough (best recall)',
+      },
+      {
+        name: '--hyde',
+        description:
+          'Use HyDE query expansion for complex queries. Improves recall 10-30% at cost of ~1-2s latency.',
       },
       { name: '--json', description: 'Output results as JSON' },
       { name: '--pretty', description: 'Pretty-print JSON output' },
+      {
+        name: '-s, --summarize',
+        description: 'Generate AI summary of search results',
+      },
+      {
+        name: '-y, --yes',
+        description: 'Skip cost confirmation for paid AI providers',
+      },
+      {
+        name: '--stream',
+        description: 'Stream AI summary output in real-time',
+      },
     ],
     notes: [
       'Auto-detects mode: semantic if embeddings exist, keyword otherwise.',
@@ -120,6 +197,29 @@ export const helpContent: Record<string, CommandHelp> = {
       'Quoted phrases match exactly: "context resumption".',
       'Regex patterns (e.g., "API.*") always use keyword search.',
       'Run "mdcontext index --embed" first for semantic search.',
+      '',
+      'Similarity threshold (--threshold):',
+      '  Default: 0.35 (35%). Results below this similarity are filtered out.',
+      '  If 0 results: content may exist below threshold. Try --threshold 0.25.',
+      '  Typical scores: single words ~30-40%, phrases ~50-70%.',
+      '  Higher threshold = stricter matching. Lower = more results.',
+      '',
+      'Re-ranking (--rerank):',
+      '  Cross-encoder model improves precision by 20-35%.',
+      '  Requires: npm install @huggingface/transformers',
+      '  Model is downloaded on first use (~90MB) and cached locally.',
+      '  Use --rerank-init to pre-download and avoid latency on first search.',
+      '',
+      'Quality modes (--quality):',
+      '  fast: efSearch=64, ~40% faster, slight recall reduction.',
+      '  balanced: efSearch=100 (default), good balance of speed and recall.',
+      '  thorough: efSearch=256, ~30% slower, best recall for large corpora.',
+      '',
+      'HyDE (--hyde):',
+      '  Generates hypothetical document using LLM, searches with that embedding.',
+      '  Best for: "how to" questions, complex queries, ambiguous searches.',
+      '  Requires: OPENAI_API_KEY (uses gpt-4o-mini by default).',
+      '  Adds ~1-2s latency, improves recall 10-30% on complex queries.',
     ],
   },
   context: {
@@ -139,6 +239,10 @@ export const helpContent: Record<string, CommandHelp> = {
       'mdcontext context doc.md --section "2.1"           # Extract by section number',
       'mdcontext context doc.md --section "API*"          # Glob pattern matching',
       'mdcontext context doc.md --section "Config" --shallow  # Top-level only',
+      '',
+      '# Section exclusion:',
+      'mdcontext context doc.md --exclude "License"       # Exclude License section',
+      'mdcontext context doc.md -x "License" -x "Test*"   # Multiple exclusions',
     ],
     options: [
       {
@@ -166,6 +270,10 @@ export const helpContent: Record<string, CommandHelp> = {
         name: '--shallow',
         description: 'Exclude nested subsections when using --section',
       },
+      {
+        name: '-x, --exclude <pattern>',
+        description: 'Exclude sections by name, number, or glob (repeatable)',
+      },
       { name: '--json', description: 'Output as JSON' },
       { name: '--pretty', description: 'Pretty-print JSON output' },
     ],
@@ -174,6 +282,7 @@ export const helpContent: Record<string, CommandHelp> = {
       'Lower tokens = more aggressive summarization.',
       'Output is formatted for direct use in LLM prompts.',
       'Use --sections to discover section names before filtering.',
+      'Exclusion: -x matches by heading name, section number, or glob pattern.',
     ],
   },
   tree: {
@@ -243,6 +352,66 @@ export const helpContent: Record<string, CommandHelp> = {
     ],
     notes: ['Shows embedding count, dimensions, and cost if embeddings exist.'],
   },
+  config: {
+    description: 'Configuration management',
+    usage: 'mdcontext config <command> [options]',
+    examples: [
+      'mdcontext config init              # Create a starter config file',
+      'mdcontext config init --format json  # Create JSON config instead of JS',
+      'mdcontext config show              # Show config file location',
+      'mdcontext config check             # Validate and show effective config',
+      'mdcontext config check --json      # Output config as JSON',
+    ],
+    options: [
+      { name: 'init', description: 'Create a starter config file' },
+      { name: 'show', description: 'Display config file location' },
+      {
+        name: 'check',
+        description: 'Validate and show effective configuration',
+      },
+      {
+        name: '-f, --format <format>',
+        description: 'Config format: js or json (init only)',
+      },
+      { name: '--force', description: 'Overwrite existing config (init only)' },
+      { name: '--json', description: 'Output as JSON' },
+      { name: '--pretty', description: 'Pretty-print JSON output' },
+    ],
+    notes: [
+      'Config files set persistent defaults for all commands.',
+      'Precedence: CLI flags > environment > config file > defaults.',
+      'See docs/CONFIG.md for full configuration reference.',
+    ],
+  },
+  embeddings: {
+    description: 'Manage embedding namespaces',
+    usage: 'mdcontext embeddings <command> [options]',
+    examples: [
+      'mdcontext embeddings list              # List all embedding namespaces',
+      'mdcontext embeddings current           # Show active namespace',
+      'mdcontext embeddings switch openai     # Switch to OpenAI embeddings',
+      'mdcontext embeddings switch voyage     # Switch to Voyage embeddings',
+      'mdcontext embeddings remove ollama     # Remove Ollama embeddings',
+      'mdcontext embeddings remove openai -f  # Force remove active namespace',
+    ],
+    options: [
+      { name: 'list', description: 'List all available embedding namespaces' },
+      { name: 'current', description: 'Show the current active namespace' },
+      {
+        name: 'switch <namespace>',
+        description: 'Switch to a different namespace',
+      },
+      { name: 'remove <namespace>', description: 'Remove a namespace' },
+      { name: '-f, --force', description: 'Force remove active namespace' },
+      { name: '--json', description: 'Output as JSON' },
+      { name: '--pretty', description: 'Pretty-print JSON output' },
+    ],
+    notes: [
+      'Namespaces store embeddings separately by provider/model.',
+      'Switching namespaces is instant - no rebuild required.',
+      'Run "mdcontext index --embed" to create embeddings for a provider.',
+    ],
+  },
 }
 
 // ============================================================================
@@ -304,6 +473,8 @@ export const showMainHelp = (): void => {
   search <query> [path]     Search by meaning or structure
   context <files>...        Get LLM-ready summary
   tree [path]               Show files or document outline
+  config <command>          Configuration management
+  embeddings <command>      Manage embedding namespaces
   links <file>              Show outgoing links
   backlinks <file>          Show incoming links
   stats [path]              Index statistics
@@ -337,11 +508,15 @@ export const showMainHelp = (): void => {
   \x1b[2m# Build semantic search\x1b[0m
   mdcontext index --embed && mdcontext search "authentication flow"
 
+  \x1b[2m# Set up project configuration\x1b[0m
+  mdcontext config init && mdcontext config check
+
 \x1b[33mGLOBAL OPTIONS\x1b[0m
-  --json          Output as JSON
-  --pretty        Pretty-print JSON
-  --help, -h      Show help
-  --version, -v   Show version
+  -c, --config <file>  Use specified config file
+  --json               Output as JSON
+  --pretty             Pretty-print JSON
+  --help, -h           Show help
+  --version, -v        Show version
 
 Run \x1b[36mmdcontext <command> --help\x1b[0m for command-specific options.
 `
@@ -371,6 +546,33 @@ export const checkSubcommandHelp = (): boolean => {
   return false
 }
 
+/**
+ * Check for bare subcommand that has nested subcommands (e.g., "config", "embeddings").
+ * Shows custom help when running "mdcontext config" without arguments.
+ * This prevents the ugly Effect CLI default output.
+ */
+export const checkBareSubcommandHelp = (): boolean => {
+  const args = process.argv.slice(2)
+
+  // Look for: exactly one arg that is a command with subcommands in helpContent
+  if (args.length !== 1) return false
+
+  const command = args[0]
+
+  // Only handle commands that have subcommands and custom help
+  const commandsWithSubcommands = ['config', 'embeddings']
+  if (
+    command &&
+    commandsWithSubcommands.includes(command) &&
+    helpContent[command]
+  ) {
+    showSubcommandHelp(command)
+    process.exit(0)
+  }
+
+  return false
+}
+
 /**
  * Check if we should show main help
  */