underrow 2026.4.1 → 2026.4.2

package/.claude/settings.local.json

@@ -3,7 +3,8 @@
     "allow": [
       "Bash(node:*)",
       "Bash(npm link:*)",
-      "Bash(knowme --help)"
+      "Bash(knowme --help)",
+      "Bash(timeout 3 bash -c 'node index.js --port 3739 &>/dev/null & PID=$!; sleep 2; curl -s http://localhost:3737/openapi.json 2>/dev/null || curl -s http://localhost:3739/openapi.json; kill $PID 2>/dev/null')"
     ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "underrow",
-  "version": "2026.4.1",
+  "version": "2026.4.2",
   "description": "KnowledgeBase driver - file watcher with vector and fuzzy search",
   "type": "module",
   "main": "index.js",
@@ -11,7 +11,12 @@
     "start": "node index.js",
     "dev": "node --watch index.js"
   },
-  "keywords": ["knowledgebase", "vector-search", "faiss", "fuzzy-search"],
+  "keywords": [
+    "knowledgebase",
+    "vector-search",
+    "faiss",
+    "fuzzy-search"
+  ],
   "license": "MIT",
   "dependencies": {
     "chokidar": "^3.6.0",

package/public/index.html

@@ -64,16 +64,6 @@
 
     .search-box input:focus { border-color: #58a6ff; }
 
-    .search-box select {
-      padding: 0.75rem;
-      background: #161b22;
-      border: 1px solid #30363d;
-      border-radius: 6px;
-      color: #e1e4e8;
-      font-size: 0.9rem;
-      cursor: pointer;
-    }
-
     .search-box button {
       padding: 0.75rem 1.5rem;
       background: #238636;
@@ -169,10 +159,6 @@
   <div class="container">
     <div class="search-box">
       <input type="text" id="query" placeholder="Search your knowledge base..." autofocus />
-      <select id="mode">
-        <option value="vector">Vector</option>
-        <option value="fuzzy">Fuzzy</option>
-      </select>
       <button onclick="doSearch()">Search</button>
     </div>
 
@@ -185,7 +171,6 @@
 
   <script>
     const queryInput = document.getElementById('query')
-    const modeSelect = document.getElementById('mode')
     const resultsDiv = document.getElementById('results')
 
     queryInput.addEventListener('keydown', e => {
@@ -206,37 +191,48 @@
       const query = queryInput.value.trim()
       if (!query) return
 
-      const mode = modeSelect.value
-      let results
-
       try {
-        if (mode === 'vector') {
-          const res = await fetch('/api/search/vector', {
+        const [vectorRes, fuzzyRes] = await Promise.all([
+          fetch('/api/search/vector', {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify({ query, k: 20 }),
-          })
-          const data = await res.json()
-          results = data.results
-        } else {
-          const res = await fetch(`/api/search/fuzzy?q=${encodeURIComponent(query)}`)
-          const data = await res.json()
-          results = data.results
-        }
-
-        renderResults(results)
+          }).then(r => r.json()),
+          fetch(`/api/search/fuzzy?q=${encodeURIComponent(query)}`).then(r => r.json()),
+        ])
+
+        renderResults(vectorRes.results, fuzzyRes.results)
       } catch (err) {
         resultsDiv.innerHTML = `<div class="empty-state">Error: ${err.message}</div>`
       }
     }
 
-    function renderResults(results) {
-      if (!results || results.length === 0) {
+    function renderResults(vectorResults, fuzzyResults) {
+      const hasVector = vectorResults && vectorResults.length > 0
+      const hasFuzzy = fuzzyResults && fuzzyResults.length > 0
+
+      if (!hasVector && !hasFuzzy) {
         resultsDiv.innerHTML = '<div class="empty-state">No results found.</div>'
         return
       }
 
-      resultsDiv.innerHTML = results.map(r => `
+      let html = ''
+
+      if (hasVector) {
+        html += '<h3 style="color:#58a6ff;margin-bottom:0.5rem">Vector Results</h3>'
+        html += vectorResults.map(renderCard).join('')
+      }
+
+      if (hasFuzzy) {
+        html += `<h3 style="color:#58a6ff;margin:${hasVector ? '1.5rem' : '0'} 0 0.5rem">Fuzzy Results</h3>`
+        html += fuzzyResults.map(renderCard).join('')
+      }
+
+      resultsDiv.innerHTML = html
+    }
+
+    function renderCard(r) {
+      return `
         <div class="result-card">
           <div class="result-header">
             <span class="result-path">${escapeHtml(r.filePath)}</span>
@@ -253,7 +249,7 @@
           </div>
           <div class="result-text">${escapeHtml(r.text)}</div>
         </div>
-      `).join('')
+      `
     }
 
     function escapeHtml(str) {

package/src/server.js

@@ -11,6 +11,42 @@ export function createServer(store, embedder) {
   app.use(express.json())
   app.use(express.static(resolve(__dirname, '..', 'public')))
 
+  // Help
+  app.get('/help', (req, res) => {
+    res.type('text/plain').send(`Underrow - KnowledgeBase Driver
+
+Underrow watches a directory for file changes, chunks the content,
+computes vector embeddings and information density, and makes
+everything searchable via a web dashboard and REST API.
+
+Routes
+------
+
+GET  /              Web dashboard with search UI and live stats
+GET  /help          This help text
+GET  /openapi.json  OpenAPI 3.0 spec for the API
+
+GET  /api/stats
+  Returns indexing statistics: file count, chunk count, average density.
+
+GET  /api/documents
+  Returns metadata for every indexed chunk.
+
+POST /api/search/vector
+  Body: { "query": "...", "k": 10 }
+  Embeds the query and returns the top-k chunks by cosine similarity.
+
+GET  /api/search/fuzzy?q=...&limit=20&threshold=0.4
+  Fuzzy text search across all indexed chunks.
+
+Environment / CLI
+-----------------
+  underrow [dir]           Directory to watch (default: cwd)
+  --port, -p <number>      Server port (default: 3737, env: KB_PORT)
+  --data, -d <path>        Data storage dir (default: ./data, env: KB_DATA_DIR)
+`)
+  })
+
   // Vector search
   app.post('/api/search/vector', async (req, res) => {
     const { query, k = 10 } = req.body
@@ -53,5 +89,136 @@ export function createServer(store, embedder) {
     res.json(store.getAllMetadata())
   })
 
+  // OpenAPI spec
+  app.get('/openapi.json', (req, res) => {
+    res.json({
+      openapi: '3.0.3',
+      info: {
+        title: 'Underrow',
+        version: '2026.4.1',
+        description: 'KnowledgeBase driver - file watcher with vector and fuzzy search',
+      },
+      paths: {
+        '/api/search/vector': {
+          post: {
+            summary: 'Vector similarity search',
+            requestBody: {
+              required: true,
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    required: ['query'],
+                    properties: {
+                      query: { type: 'string', description: 'Search text to embed and match against indexed chunks' },
+                      k: { type: 'integer', default: 10, description: 'Number of results to return' },
+                    },
+                  },
+                },
+              },
+            },
+            responses: {
+              200: {
+                description: 'Search results ranked by cosine similarity',
+                content: { 'application/json': { schema: { $ref: '#/components/schemas/SearchResults' } } },
+              },
+              400: { description: 'Missing query' },
+            },
+          },
+        },
+        '/api/search/fuzzy': {
+          get: {
+            summary: 'Fuzzy text search',
+            parameters: [
+              { name: 'q', in: 'query', required: true, schema: { type: 'string' }, description: 'Search query' },
+              { name: 'limit', in: 'query', schema: { type: 'integer', default: 20 }, description: 'Max results' },
+              { name: 'threshold', in: 'query', schema: { type: 'number', default: 0.4 }, description: 'Fuse.js match threshold (0 = exact, 1 = anything)' },
+            ],
+            responses: {
+              200: {
+                description: 'Fuzzy-matched results',
+                content: { 'application/json': { schema: { $ref: '#/components/schemas/SearchResults' } } },
+              },
+              400: { description: 'Missing q parameter' },
+            },
+          },
+        },
+        '/api/stats': {
+          get: {
+            summary: 'Index statistics',
+            responses: {
+              200: {
+                description: 'Current indexing stats',
+                content: {
+                  'application/json': {
+                    schema: {
+                      type: 'object',
+                      properties: {
+                        files: { type: 'integer' },
+                        chunks: { type: 'integer' },
+                        avgDensity: { type: 'number' },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+        '/api/documents': {
+          get: {
+            summary: 'All indexed document metadata',
+            responses: {
+              200: {
+                description: 'Array of chunk metadata',
+                content: {
+                  'application/json': {
+                    schema: {
+                      type: 'array',
+                      items: { $ref: '#/components/schemas/ChunkMeta' },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      components: {
+        schemas: {
+          ChunkMeta: {
+            type: 'object',
+            properties: {
+              id: { type: 'integer' },
+              filePath: { type: 'string' },
+              chunkIndex: { type: 'integer' },
+              text: { type: 'string' },
+              density: { type: 'number' },
+              mtime: { type: 'number' },
+            },
+          },
+          SearchResults: {
+            type: 'object',
+            properties: {
+              results: {
+                type: 'array',
+                items: {
+                  type: 'object',
+                  properties: {
+                    score: { type: 'number' },
+                    filePath: { type: 'string' },
+                    chunkIndex: { type: 'integer' },
+                    text: { type: 'string' },
+                    density: { type: 'number' },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    })
+  })
+
   return app
 }