mdcontext 0.1.0 → 0.2.0

package/scripts/apply-branch-protection.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+# Apply branch protection from a template
+# Usage: ./apply-branch-protection.sh owner/repo template [branch]
+#
+# Templates: full-ci-matrix, simple, minimal, strict
+#
+# Examples:
+#   ./apply-branch-protection.sh mdcontext/mdcontext full-ci-matrix
+#   ./apply-branch-protection.sh myorg/myrepo simple main
+#   ./apply-branch-protection.sh myorg/myrepo minimal develop
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TEMPLATES_FILE="$SCRIPT_DIR/branch-protection-templates.json"
+
+REPO="${1:?Usage: $0 owner/repo template [branch]}"
+TEMPLATE="${2:?Usage: $0 owner/repo template [branch] (templates: full-ci-matrix, simple, minimal, strict)}"
+BRANCH="${3:-main}"
+
+if [[ ! -f "$TEMPLATES_FILE" ]]; then
+  echo "Error: Templates file not found at $TEMPLATES_FILE"
+  exit 1
+fi
+
+# Extract template (remove description field for API)
+CONFIG=$(jq -r ".[\"$TEMPLATE\"] | del(.description)" "$TEMPLATES_FILE")
+
+if [[ "$CONFIG" == "null" ]]; then
+  echo "Error: Template '$TEMPLATE' not found"
+  echo "Available templates:"
+  jq -r 'keys[]' "$TEMPLATES_FILE"
+  exit 1
+fi
+
+DESCRIPTION=$(jq -r ".[\"$TEMPLATE\"].description // \"\"" "$TEMPLATES_FILE")
+
+echo "Applying branch protection to $REPO ($BRANCH branch)"
+echo "Template: $TEMPLATE"
+[[ -n "$DESCRIPTION" ]] && echo "  $DESCRIPTION"
+echo ""
+
+echo "$CONFIG" | gh api "repos/$REPO/branches/$BRANCH/protection" -X PUT --input - > /dev/null
+
+echo "Done! Branch protection configured."
+echo ""
+echo "View settings: https://github.com/$REPO/settings/branches"

package/scripts/branch-protection-templates.json

@@ -0,0 +1,79 @@
+{
+	"full-ci-matrix": {
+		"description": "For projects with quality + multi-platform test matrix (Node 20/22, ubuntu/macos/windows)",
+		"required_status_checks": {
+			"strict": true,
+			"contexts": [
+				"quality",
+				"test (ubuntu-latest, 20)",
+				"test (ubuntu-latest, 22)",
+				"test (macos-latest, 20)",
+				"test (macos-latest, 22)",
+				"test (windows-latest, 20)",
+				"test (windows-latest, 22)"
+			]
+		},
+		"enforce_admins": false,
+		"required_pull_request_reviews": {
+			"required_approving_review_count": 1,
+			"dismiss_stale_reviews": true,
+			"require_code_owner_reviews": false
+		},
+		"restrictions": null,
+		"required_linear_history": true,
+		"allow_force_pushes": false,
+		"allow_deletions": false
+	},
+
+	"simple": {
+		"description": "For simple projects with build + test jobs",
+		"required_status_checks": {
+			"strict": true,
+			"contexts": ["build", "test"]
+		},
+		"enforce_admins": false,
+		"required_pull_request_reviews": {
+			"required_approving_review_count": 1,
+			"dismiss_stale_reviews": true,
+			"require_code_owner_reviews": false
+		},
+		"restrictions": null,
+		"required_linear_history": true,
+		"allow_force_pushes": false,
+		"allow_deletions": false
+	},
+
+	"minimal": {
+		"description": "Minimal protection - just require PR reviews",
+		"required_status_checks": null,
+		"enforce_admins": false,
+		"required_pull_request_reviews": {
+			"required_approving_review_count": 1,
+			"dismiss_stale_reviews": true,
+			"require_code_owner_reviews": false
+		},
+		"restrictions": null,
+		"required_linear_history": false,
+		"allow_force_pushes": false,
+		"allow_deletions": false
+	},
+
+	"strict": {
+		"description": "Strict protection with admin enforcement and code owners",
+		"required_status_checks": {
+			"strict": true,
+			"contexts": ["ci"]
+		},
+		"enforce_admins": true,
+		"required_pull_request_reviews": {
+			"required_approving_review_count": 2,
+			"dismiss_stale_reviews": true,
+			"require_code_owner_reviews": true,
+			"require_last_push_approval": true
+		},
+		"restrictions": null,
+		"required_linear_history": true,
+		"allow_force_pushes": false,
+		"allow_deletions": false
+	}
+}

package/scripts/prototype-summarization.ts

@@ -0,0 +1,346 @@
+#!/usr/bin/env npx tsx
+/**
+ * Prototype: AI Summarization of Search Results
+ *
+ * Quick validation script to test the summarization approach.
+ * Uses the actual mdcontext search and Claude CLI integration.
+ *
+ * Usage:
+ *   npx tsx scripts/prototype-summarization.ts
+ *   npx tsx scripts/prototype-summarization.ts "your query here"
+ */
+
+import { spawn } from 'node:child_process'
+import * as path from 'node:path'
+import * as fs from 'node:fs'
+
+// Test queries to validate the approach
+const TEST_QUERIES = [
+  'error handling',
+  'configuration',
+  'search',
+  'embeddings',
+  'Effect patterns',
+]
+
+interface SearchResult {
+  path: string
+  heading: string
+  score?: number
+  similarity?: number
+}
+
+interface SummaryResult {
+  query: string
+  searchResults: SearchResult[]
+  summary: string
+  durationMs: number
+  provider: string
+}
+
+/**
+ * Run mdcontext search and get JSON results
+ */
+async function runSearch(query: string, dir: string): Promise<SearchResult[]> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn('node', [
+      path.join(dir, 'dist/cli/main.js'),
+      'search',
+      query,
+      dir,
+      '--json',
+      '--limit', '5',
+    ], {
+      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) => {
+      if (code !== 0) {
+        // If search fails (no index), return empty results
+        console.log(`  Search returned code ${code}, using empty results`)
+        resolve([])
+        return
+      }
+
+      try {
+        const parsed = JSON.parse(stdout)
+        const results = (parsed.results || []).map((r: any) => ({
+          path: r.path,
+          heading: r.heading,
+          score: r.score,
+          similarity: r.similarity,
+        }))
+        resolve(results)
+      } catch (e) {
+        console.log(`  Failed to parse search results: ${e}`)
+        resolve([])
+      }
+    })
+
+    proc.on('error', (err) => {
+      reject(err)
+    })
+  })
+}
+
+/**
+ * Format search results for LLM input
+ */
+function formatResultsForLLM(query: string, results: SearchResult[]): string {
+  if (results.length === 0) {
+    return `Query: "${query}"\n\nNo search results found. The index may need to be built.`
+  }
+
+  const resultsText = results.map((r, i) => {
+    const score = r.similarity
+      ? `${(r.similarity * 100).toFixed(1)}% similarity`
+      : r.score
+        ? `score: ${r.score.toFixed(2)}`
+        : ''
+    return `${i + 1}. ${r.path}\n   Section: ${r.heading}\n   ${score}`
+  }).join('\n\n')
+
+  return `Query: "${query}"
+
+Search Results (${results.length} found):
+
+${resultsText}
+
+Please provide a concise summary of what these results tell us about "${query}" in this codebase.
+Focus on:
+1. Key patterns and approaches found
+2. Important files to look at
+3. Actionable next steps for the developer`
+}
+
+/**
+ * Call Claude CLI for summarization
+ * SECURITY: Uses spawn() with argument arrays - never exec() with strings
+ */
+async function callClaudeCLI(prompt: string): Promise<{ summary: string; durationMs: number }> {
+  const startTime = Date.now()
+
+  return new Promise((resolve, reject) => {
+    // SECURITY: spawn() with argument array - safe from shell injection
+    const proc = spawn('claude', [
+      '-p', prompt,
+      '--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()
+    })
+
+    // Timeout after 60 seconds
+    const timeout = setTimeout(() => {
+      proc.kill('SIGTERM')
+      reject(new Error('Claude CLI timeout after 60s'))
+    }, 60000)
+
+    proc.on('close', (code: number | null) => {
+      clearTimeout(timeout)
+      const durationMs = Date.now() - startTime
+
+      if (code !== 0) {
+        reject(new Error(`Claude CLI exited with code ${code}: ${stderr}`))
+        return
+      }
+
+      resolve({
+        summary: stdout.trim(),
+        durationMs,
+      })
+    })
+
+    proc.on('error', (err) => {
+      clearTimeout(timeout)
+      reject(new Error(`Failed to spawn Claude CLI: ${err.message}`))
+    })
+  })
+}
+
+/**
+ * Check if Claude CLI is available
+ */
+async function checkClaudeCLI(): Promise<boolean> {
+  return new Promise((resolve) => {
+    const proc = spawn('which', ['claude'], {
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+
+    proc.on('close', (code) => {
+      resolve(code === 0)
+    })
+
+    proc.on('error', () => {
+      resolve(false)
+    })
+  })
+}
+
+/**
+ * Run a single test query
+ */
+async function testQuery(query: string, projectDir: string): Promise<SummaryResult> {
+  console.log(`\n${'='.repeat(60)}`)
+  console.log(`Query: "${query}"`)
+  console.log('='.repeat(60))
+
+  // 1. Run search
+  console.log('\n1. Running search...')
+  const searchResults = await runSearch(query, projectDir)
+  console.log(`   Found ${searchResults.length} results`)
+
+  // 2. Format for LLM
+  const prompt = formatResultsForLLM(query, searchResults)
+
+  // 3. Call Claude CLI
+  console.log('\n2. Calling Claude CLI for summary...')
+  const { summary, durationMs } = await callClaudeCLI(prompt)
+
+  // 4. Display result
+  console.log(`\n3. Summary (${durationMs}ms):`)
+  console.log('-'.repeat(40))
+  console.log(summary)
+  console.log('-'.repeat(40))
+
+  return {
+    query,
+    searchResults,
+    summary,
+    durationMs,
+    provider: 'claude',
+  }
+}
+
+/**
+ * Main prototype function
+ */
+async function main() {
+  const projectDir = path.resolve(import.meta.dirname, '..')
+  console.log('Prototype: AI Summarization of Search Results')
+  console.log(`Project: ${projectDir}`)
+
+  // Check Claude CLI
+  const hasClaudeCLI = await checkClaudeCLI()
+  if (!hasClaudeCLI) {
+    console.error('\nError: Claude CLI not found.')
+    console.error('Install it from: https://claude.ai/download')
+    process.exit(1)
+  }
+  console.log('Claude CLI: available')
+
+  // Get query from args or use test queries
+  const args = process.argv.slice(2)
+  const queries = args.length > 0 ? args : TEST_QUERIES
+
+  // Run tests
+  const results: SummaryResult[] = []
+  for (const query of queries) {
+    try {
+      const result = await testQuery(query, projectDir)
+      results.push(result)
+    } catch (err) {
+      console.error(`\nError testing "${query}":`, err)
+    }
+  }
+
+  // Summary
+  console.log('\n' + '='.repeat(60))
+  console.log('PROTOTYPE RESULTS SUMMARY')
+  console.log('='.repeat(60))
+  console.log(`\nQueries tested: ${results.length}`)
+  console.log(`Total duration: ${results.reduce((sum, r) => sum + r.durationMs, 0)}ms`)
+  console.log(`Average duration: ${Math.round(results.reduce((sum, r) => sum + r.durationMs, 0) / results.length)}ms`)
+
+  // Write results to file
+  const outputPath = path.join(projectDir, 'research/llm-summarization/prototype-results.md')
+  const outputDir = path.dirname(outputPath)
+
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true })
+  }
+
+  const markdown = generateResultsMarkdown(results)
+  fs.writeFileSync(outputPath, markdown)
+  console.log(`\nResults written to: ${outputPath}`)
+}
+
+/**
+ * Generate markdown report from results
+ */
+function generateResultsMarkdown(results: SummaryResult[]): string {
+  const timestamp = new Date().toISOString()
+  const totalDuration = results.reduce((sum, r) => sum + r.durationMs, 0)
+  const avgDuration = Math.round(totalDuration / results.length)
+
+  let md = `# Prototype Results: AI Summarization
+
+Generated: ${timestamp}
+
+## Summary
+
+- **Queries tested:** ${results.length}
+- **Total duration:** ${totalDuration}ms
+- **Average duration:** ${avgDuration}ms
+- **Provider:** Claude CLI (free with subscription)
+
+## Results
+
+`
+
+  for (const result of results) {
+    md += `### Query: "${result.query}"
+
+**Search Results:** ${result.searchResults.length} found
+**Duration:** ${result.durationMs}ms
+
+#### Summary
+
+${result.summary}
+
+---
+
+`
+  }
+
+  md += `## Findings
+
+### What Works Well
+
+- [ ] Add observations here after running prototype
+
+### Issues Discovered
+
+- [ ] Add issues here after running prototype
+
+### Recommendations
+
+- [ ] Add recommendations here after running prototype
+`
+
+  return md
+}
+
+// Run
+main().catch(console.error)

package/scripts/rebuild-hnswlib.js

@@ -7,57 +7,52 @@ import { existsSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 
 function findHnswlibDir() {
-  const pnpmDir = join(process.cwd(), "node_modules", ".pnpm");
-
-  if (!existsSync(pnpmDir)) {
-    return null;
-  }
-
-  const entries = readdirSync(pnpmDir);
-  for (const entry of entries) {
-    if (entry.startsWith("hnswlib-node@")) {
-      const candidate = join(
-        pnpmDir,
-        entry,
-        "node_modules",
-        "hnswlib-node"
-      );
-      if (existsSync(candidate) && statSync(candidate).isDirectory()) {
-        return candidate;
-      }
-    }
-  }
-
-  return null;
+	const pnpmDir = join(process.cwd(), "node_modules", ".pnpm");
+
+	if (!existsSync(pnpmDir)) {
+		return null;
+	}
+
+	const entries = readdirSync(pnpmDir);
+	for (const entry of entries) {
+		if (entry.startsWith("hnswlib-node@")) {
+			const candidate = join(pnpmDir, entry, "node_modules", "hnswlib-node");
+			if (existsSync(candidate) && statSync(candidate).isDirectory()) {
+				return candidate;
+			}
+		}
+	}
+
+	return null;
 }
 
 const hnswlibDir = findHnswlibDir();
 
 if (!hnswlibDir) {
-  console.log("hnswlib-node not found, skipping rebuild");
-  process.exit(0);
+	console.log("hnswlib-node not found, skipping rebuild");
+	process.exit(0);
 }
 
 const addonPath = join(hnswlibDir, "build", "Release", "addon.node");
 if (existsSync(addonPath)) {
-  console.log("hnswlib-node already built, skipping");
-  process.exit(0);
+	console.log("hnswlib-node already built, skipping");
+	process.exit(0);
 }
 
 console.log("Building hnswlib-node native module...");
 console.log(`  Directory: ${hnswlibDir}`);
 
 try {
-  execSync("npx node-gyp rebuild", {
-    cwd: hnswlibDir,
-    stdio: "inherit",
-  });
-  console.log("hnswlib-node build complete");
+	execSync("npx node-gyp rebuild", {
+		cwd: hnswlibDir,
+		stdio: "inherit",
+	});
+	console.log("hnswlib-node build complete");
 } catch (error) {
-  console.error("Failed to build hnswlib-node:", error.message);
-  console.error("You may need to install build tools:");
-  console.error("  - macOS: xcode-select --install");
-  console.error("  - Ubuntu: apt install python3 make g++");
-  console.error("  - Windows: npm install -g windows-build-tools");
-  process.exit(1);
+	console.error("Failed to build hnswlib-node:", error.message);
+	console.error("You may need to install build tools:");
+	console.error("  - macOS: xcode-select --install");
+	console.error("  - Ubuntu: apt install python3 make g++");
+	console.error("  - Windows: npm install -g windows-build-tools");
+	process.exit(1);
 }

package/scripts/setup-branch-protection.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+# Setup branch protection for a GitHub repository
+# Usage: ./setup-branch-protection.sh owner/repo [branch]
+#
+# Example:
+#   ./setup-branch-protection.sh mdcontext/mdcontext main
+#   ./setup-branch-protection.sh myorg/myrepo
+
+set -e
+
+REPO="${1:?Usage: $0 owner/repo [branch]}"
+BRANCH="${2:-main}"
+
+echo "Setting up branch protection for $REPO ($BRANCH branch)..."
+
+# Customize these status checks for your CI workflow
+# Comment out or modify based on your needs
+STATUS_CHECKS='[
+  "quality",
+  "test (ubuntu-latest, 20)",
+  "test (ubuntu-latest, 22)",
+  "test (macos-latest, 20)",
+  "test (macos-latest, 22)",
+  "test (windows-latest, 20)",
+  "test (windows-latest, 22)"
+]'
+
+# For simpler projects, you might use:
+# STATUS_CHECKS='["build", "test"]'
+
+cat << EOF | gh api "repos/$REPO/branches/$BRANCH/protection" -X PUT --input -
+{
+  "required_status_checks": {
+    "strict": true,
+    "contexts": $STATUS_CHECKS
+  },
+  "enforce_admins": false,
+  "required_pull_request_reviews": {
+    "required_approving_review_count": 1,
+    "dismiss_stale_reviews": true,
+    "require_code_owner_reviews": false,
+    "require_last_push_approval": false
+  },
+  "restrictions": null,
+  "required_linear_history": true,
+  "allow_force_pushes": false,
+  "allow_deletions": false,
+  "block_creations": false,
+  "required_conversation_resolution": false,
+  "lock_branch": false,
+  "allow_fork_syncing": false
+}
+EOF
+
+echo "Branch protection configured for $REPO ($BRANCH)"
+echo ""
+echo "Settings applied:"
+echo "  - Require status checks to pass before merging"
+echo "  - Require branches to be up to date before merging"
+echo "  - Require 1 approving review"
+echo "  - Dismiss stale reviews on new commits"
+echo "  - Require linear history (no merge commits)"
+echo "  - Block force pushes"
+echo "  - Block branch deletion"

package/src/__tests__/fixtures/semantic-search/multi-word-corpus/.mdcontext/active-provider.json

@@ -0,0 +1,7 @@
+{
+  "namespace": "openai_text-embedding-3-small_512",
+  "provider": "openai",
+  "model": "text-embedding-3-small",
+  "dimensions": 512,
+  "activatedAt": "2026-01-27T00:00:00.000Z"
+}