claude-transcript-viewer 1.1.0

package/README.md

@@ -0,0 +1,215 @@
+# Claude Transcript Viewer
+
+A web server for browsing and searching Claude Code conversation transcripts with semantic search, infinite scroll, and collapsible cells.
+
+## Features
+
+- **Semantic Search** - Hybrid FTS + vector search with highlighted snippets
+- **Auto Archive Generation** - Automatically generates HTML from JSONL transcripts on startup
+- **Background Indexing** - Non-blocking indexing of conversations for search
+- **Enhanced Viewing** - Collapsible cells, preview text, infinite scroll
+- **Search Everywhere** - Search bar on every page with live dropdown results
+- **Full Search Page** - Dedicated search results page with filters (project, role, date)
+
+## Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Start with auto-generation (recommended)
+SOURCE_DIR=~/.claude/projects npm run dev
+
+# Or specify output directory
+ARCHIVE_DIR=./archive SOURCE_DIR=~/.claude/projects npm run dev
+```
+
+Open http://localhost:3000 to browse transcripts.
+
+## Installation
+
+```bash
+git clone <repo>
+cd claude-transcript-viewer
+npm install
+```
+
+### Requirements
+
+- Node.js 18+
+- [claude-code-transcripts](https://github.com/simonw/claude-code-transcripts) Python CLI (for HTML generation)
+
+```bash
+# Install the Python CLI
+pip install claude-code-transcripts
+# or
+uv pip install claude-code-transcripts
+```
+
+## Usage
+
+### Basic Usage
+
+```bash
+# Auto-generate archive and start server
+SOURCE_DIR=~/.claude/projects npm run dev
+
+# Use existing archive (no generation)
+npm run dev -- /path/to/existing/archive
+
+# Specify all paths explicitly
+ARCHIVE_DIR=./archive \
+SOURCE_DIR=~/.claude/projects \
+DATABASE_PATH=./search.db \
+npm run dev
+```
+
+### Manual Indexing
+
+If you only want to index without running the server:
+
+```bash
+npm run index ~/.claude/projects ./search.db
+```
+
+### With Embedding Server
+
+For semantic vector search (optional), run a compatible embedding server:
+
+```bash
+# Start embedding server (e.g., qwen3-embeddings-mlx)
+EMBED_SOCKET=/tmp/qwen-embed.sock npm run dev
+```
+
+## Configuration
+
+| Environment Variable | Default | Description |
+|---------------------|---------|-------------|
+| `PORT` | `3000` | Server port |
+| `ARCHIVE_DIR` | `./claude-archive` | Directory for HTML files |
+| `SOURCE_DIR` | (none) | JSONL source directory (enables auto-generation) |
+| `DATABASE_PATH` | `ARCHIVE_DIR/.search.db` | SQLite database path |
+| `EMBED_SOCKET` | `/tmp/qwen-embed.sock` | Unix socket for embedding server |
+
+## API Endpoints
+
+### Search
+
+```bash
+# Search conversations
+GET /api/search?q=sqlite&limit=20
+
+# With filters
+GET /api/search?q=typescript&project=my-project&role=assistant
+
+# Parameters:
+# - q: Search query
+# - project: Filter by project name
+# - role: Filter by role (user/assistant)
+# - after: Filter by date (YYYY-MM-DD)
+# - before: Filter by date (YYYY-MM-DD)
+# - limit: Max results (default: 20)
+# - offset: Pagination offset
+```
+
+### Status
+
+```bash
+# Get index and archive status
+GET /api/index/status
+
+# Response:
+{
+  "status": "ready",
+  "conversations": 3471,
+  "chunks": 596168,
+  "embedding_server": "unavailable",
+  "archive": {
+    "isGenerating": false,
+    "progress": "Complete",
+    "lastRun": "2026-01-21T19:21:27Z"
+  },
+  "indexing": {
+    "isIndexing": false,
+    "progress": "Complete",
+    "lastStats": { "added": 37, "modified": 0, "deleted": 0, "chunks": 16513 }
+  }
+}
+```
+
+### Manual Triggers
+
+```bash
+# Regenerate HTML archive and re-index
+POST /api/archive/regenerate
+
+# Re-index only (no HTML regeneration)
+POST /api/index/reindex
+```
+
+## Pages
+
+| Route | Description |
+|-------|-------------|
+| `/` | Landing page with projects and recent conversations |
+| `/search?q=...` | Full search results page with filters |
+| `/*.html` | Enhanced transcript pages with search bar |
+
+## Architecture
+
+```
+JSONL files ─┬─> claude-code-transcripts (Python) ─> HTML files
+             │
+             └─> transcript-viewer indexer ─> SQLite (FTS + vectors)
+
+HTML files ─> Express server ─> Enhanced HTML + Search API
+```
+
+### Search Pipeline
+
+1. **FTS5** - Full-text search with trigram tokenizer for substring matching
+2. **Vector Search** - Semantic similarity using sqlite-vec (when embedding server available)
+3. **RRF Merge** - Reciprocal Rank Fusion combines both result sets
+4. **Snippets** - Generates highlighted snippets around matched terms
+
+## Development
+
+```bash
+# Run tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Build for production
+npm run build
+
+# Start production server
+npm start
+```
+
+### Project Structure
+
+```
+src/
+├── server.ts           # Express server, routes, HTML enhancement
+├── api/
+│   ├── search.ts       # Hybrid search (FTS + vector + RRF)
+│   └── snippets.ts     # Snippet generation and highlighting
+├── db/
+│   ├── index.ts        # Database initialization
+│   ├── schema.ts       # Tables, indexes, triggers
+│   ├── chunks.ts       # Chunk CRUD operations
+│   └── conversations.ts # Conversation CRUD operations
+├── indexer/
+│   ├── index.ts        # Main indexing logic
+│   ├── parser.ts       # JSONL transcript parser
+│   ├── chunker.ts      # Text chunking
+│   └── fileUtils.ts    # File hashing, mtime detection
+└── embeddings/
+    └── client.ts       # Unix socket client for embedding server
+```
+
+## License
+
+MIT

package/dist/api/search.d.ts

@@ -0,0 +1,50 @@
+import { Conversation } from '../db/conversations.js';
+import { EmbeddingClient } from '../embeddings/client.js';
+export interface SearchOptions {
+    project?: string;
+    role?: 'user' | 'assistant';
+    after?: string;
+    before?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface SearchResult {
+    chunk_id: number;
+    conversation_id: string;
+    title: string | null;
+    project: string;
+    role: string;
+    content: string;
+    page_number: number | null;
+    score: number;
+}
+export declare function searchVector(queryEmbedding: Buffer, opts: SearchOptions): SearchResult[];
+export declare function searchFTS(query: string, opts: SearchOptions): SearchResult[];
+export interface RRFOptions {
+    limit?: number;
+    k?: number;
+}
+/**
+ * Merge results from vector and FTS search using Reciprocal Rank Fusion.
+ * RRF combines rankings by computing: score(doc) = Σ 1/(k + rank)
+ * Documents appearing in both result sets get boosted scores.
+ */
+export declare function mergeResultsRRF(vectorResults: SearchResult[], ftsResults: SearchResult[], options?: RRFOptions): SearchResult[];
+export interface HybridSearchResult {
+    type: 'hybrid' | 'fts_only' | 'recent';
+    results?: SearchResult[];
+    conversations?: Conversation[];
+    embeddingStatus?: 'available' | 'unavailable';
+}
+/**
+ * Perform hybrid search combining vector and FTS results with RRF.
+ * Falls back to FTS-only when embeddings unavailable.
+ * Returns recent conversations for empty queries.
+ */
+export declare function searchHybrid(query: string, opts: SearchOptions, embeddingClient?: EmbeddingClient): Promise<HybridSearchResult>;
+export interface SearchWithFallbackResult {
+    type: 'search' | 'recent';
+    results?: SearchResult[];
+    conversations?: Conversation[];
+}
+export declare function searchWithFallback(query: string, opts: SearchOptions): SearchWithFallbackResult;

package/dist/api/search.js

@@ -0,0 +1,181 @@
+import { getDatabase } from '../db/index.js';
+import { sanitizeFTSQuery } from '../db/chunks.js';
+import { getRecentConversations, listConversations, } from '../db/conversations.js';
+export function searchVector(queryEmbedding, opts) {
+    const db = getDatabase();
+    const { project, role, after, before, limit = 100, offset = 0 } = opts;
+    if (limit < 0 || offset < 0)
+        return [];
+    let sql = `
+    SELECT
+      c.id as chunk_id,
+      c.conversation_id,
+      conv.title,
+      conv.project,
+      c.role,
+      c.content,
+      c.page_number,
+      vec_distance_cosine(cv.embedding, ?) as score
+    FROM chunks c
+    JOIN chunks_vec cv ON cv.rowid = c.id
+    JOIN conversations conv ON conv.id = c.conversation_id
+    WHERE 1=1
+  `;
+    const params = [queryEmbedding];
+    if (project) {
+        sql += ' AND conv.project = ?';
+        params.push(project);
+    }
+    if (role) {
+        sql += ' AND c.role = ?';
+        params.push(role);
+    }
+    if (after) {
+        sql += ' AND conv.created_at >= ?';
+        params.push(after);
+    }
+    if (before) {
+        sql += ' AND conv.created_at <= ?';
+        params.push(before);
+    }
+    sql += ' ORDER BY score ASC LIMIT ? OFFSET ?';
+    params.push(limit, offset);
+    return db.prepare(sql).all(...params);
+}
+export function searchFTS(query, opts) {
+    const db = getDatabase();
+    const { project, role, after, before, limit = 20, offset = 0 } = opts;
+    if (limit < 0 || offset < 0)
+        return [];
+    const sanitized = sanitizeFTSQuery(query);
+    if (!sanitized)
+        return [];
+    let sql = `
+    SELECT
+      c.id as chunk_id,
+      c.conversation_id,
+      conv.title,
+      conv.project,
+      c.role,
+      c.content,
+      c.page_number,
+      bm25(chunks_fts) as score
+    FROM chunks_fts fts
+    JOIN chunks c ON c.id = fts.rowid
+    JOIN conversations conv ON conv.id = c.conversation_id
+    WHERE chunks_fts MATCH ?
+  `;
+    const params = [sanitized];
+    if (project) {
+        sql += ' AND conv.project = ?';
+        params.push(project);
+    }
+    if (role) {
+        sql += ' AND c.role = ?';
+        params.push(role);
+    }
+    if (after) {
+        sql += ' AND conv.created_at >= ?';
+        params.push(after);
+    }
+    if (before) {
+        sql += ' AND conv.created_at <= ?';
+        params.push(before);
+    }
+    sql += ' ORDER BY score LIMIT ? OFFSET ?';
+    params.push(limit, offset);
+    return db.prepare(sql).all(...params);
+}
+/**
+ * Merge results from vector and FTS search using Reciprocal Rank Fusion.
+ * RRF combines rankings by computing: score(doc) = Σ 1/(k + rank)
+ * Documents appearing in both result sets get boosted scores.
+ */
+export function mergeResultsRRF(vectorResults, ftsResults, options = {}) {
+    const { limit = 20, k = 60 } = options;
+    // Map chunk_id to combined RRF score and first-seen result data
+    const scores = new Map();
+    const resultData = new Map();
+    // Process vector results
+    vectorResults.forEach((result, rank) => {
+        const rrfScore = 1 / (k + rank);
+        scores.set(result.chunk_id, (scores.get(result.chunk_id) || 0) + rrfScore);
+        if (!resultData.has(result.chunk_id)) {
+            resultData.set(result.chunk_id, result);
+        }
+    });
+    // Process FTS results
+    ftsResults.forEach((result, rank) => {
+        const rrfScore = 1 / (k + rank);
+        scores.set(result.chunk_id, (scores.get(result.chunk_id) || 0) + rrfScore);
+        if (!resultData.has(result.chunk_id)) {
+            resultData.set(result.chunk_id, result);
+        }
+    });
+    // Sort by combined score (descending) and limit
+    const sortedIds = [...scores.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, limit)
+        .map(([id]) => id);
+    // Build final results with updated scores
+    return sortedIds.map((id) => ({
+        ...resultData.get(id),
+        score: scores.get(id),
+    }));
+}
+/**
+ * Perform hybrid search combining vector and FTS results with RRF.
+ * Falls back to FTS-only when embeddings unavailable.
+ * Returns recent conversations for empty queries.
+ */
+export async function searchHybrid(query, opts, embeddingClient) {
+    const trimmed = query.trim();
+    // Empty query: return recent conversations
+    if (!trimmed) {
+        const conversations = opts.project
+            ? listConversations(opts.project)
+            : getRecentConversations(opts.limit || 20);
+        return { type: 'recent', conversations };
+    }
+    // Try to get embedding for the query
+    let queryEmbedding = null;
+    if (embeddingClient) {
+        const embeddingResult = await embeddingClient.embed(trimmed);
+        if (embeddingResult) {
+            // Convert number[] to Float32Array buffer
+            queryEmbedding = Buffer.from(new Float32Array(embeddingResult.embedding).buffer);
+        }
+    }
+    // Always get FTS results
+    const ftsResults = searchFTS(query, { ...opts, limit: 100 });
+    // If we have embeddings, do hybrid search
+    if (queryEmbedding) {
+        const vectorResults = searchVector(queryEmbedding, { ...opts, limit: 100 });
+        const merged = mergeResultsRRF(vectorResults, ftsResults, {
+            limit: opts.limit || 20,
+        });
+        return {
+            type: 'hybrid',
+            results: merged,
+            embeddingStatus: 'available',
+        };
+    }
+    // Fallback to FTS-only
+    return {
+        type: 'fts_only',
+        results: ftsResults.slice(0, opts.limit || 20),
+        embeddingStatus: 'unavailable',
+    };
+}
+export function searchWithFallback(query, opts) {
+    const trimmed = query.trim();
+    if (!trimmed) {
+        const conversations = opts.project
+            ? listConversations(opts.project)
+            : getRecentConversations(opts.limit || 20);
+        return { type: 'recent', conversations };
+    }
+    const results = searchFTS(query, opts);
+    return { type: 'search', results };
+}
+//# sourceMappingURL=search.js.map

package/dist/api/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/api/search.ts"],"names":[],"mappings":"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"}

package/dist/api/snippets.d.ts

@@ -0,0 +1,2 @@
+export declare function generateSnippet(content: string, query: string, contextChars?: number): string;
+export declare function highlightTerms(text: string, terms: string[]): string;

package/dist/api/snippets.js

@@ -0,0 +1,49 @@
+export function generateSnippet(content, query, contextChars = 75) {
+    // Strip markdown bold markers to avoid double-highlighting
+    const cleanContent = content.replace(/\*\*/g, '');
+    const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+    const lower = cleanContent.toLowerCase();
+    let matchIdx = -1;
+    for (const term of terms) {
+        const idx = lower.indexOf(term);
+        if (idx !== -1 && (matchIdx === -1 || idx < matchIdx)) {
+            matchIdx = idx;
+        }
+    }
+    if (matchIdx === -1) {
+        const maxLen = contextChars * 2;
+        return cleanContent.length > maxLen
+            ? cleanContent.slice(0, maxLen) + '...'
+            : cleanContent;
+    }
+    const start = Math.max(0, matchIdx - contextChars);
+    const end = Math.min(cleanContent.length, matchIdx + contextChars);
+    let snippet = cleanContent.slice(start, end);
+    if (start > 0)
+        snippet = '...' + snippet;
+    if (end < cleanContent.length)
+        snippet = snippet + '...';
+    return snippet;
+}
+function escapeHtml(str) {
+    return str
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+export function highlightTerms(text, terms) {
+    // First escape HTML to prevent XSS
+    let result = escapeHtml(text);
+    // Then wrap matched terms in <strong> tags
+    for (const term of terms) {
+        if (!term)
+            continue;
+        const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const regex = new RegExp(`(${escaped})`, 'gi');
+        result = result.replace(regex, '<strong>$1</strong>');
+    }
+    return result;
+}
+//# sourceMappingURL=snippets.js.map

package/dist/api/snippets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snippets.js","sourceRoot":"","sources":["../../src/api/snippets.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,eAAe,CAAC,OAAe,EAAE,KAAa,EAAE,YAAY,GAAG,EAAE;IAC/E,2DAA2D;IAC3D,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAClD,MAAM,KAAK,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC/D,MAAM,KAAK,GAAG,YAAY,CAAC,WAAW,EAAE,CAAC;IAEzC,IAAI,QAAQ,GAAG,CAAC,CAAC,CAAC;IAClB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,QAAQ,KAAK,CAAC,CAAC,IAAI,GAAG,GAAG,QAAQ,CAAC,EAAE,CAAC;YACtD,QAAQ,GAAG,GAAG,CAAC;QACjB,CAAC;IACH,CAAC;IAED,IAAI,QAAQ,KAAK,CAAC,CAAC,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,YAAY,GAAG,CAAC,CAAC;QAChC,OAAO,YAAY,CAAC,MAAM,GAAG,MAAM;YACjC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,KAAK;YACvC,CAAC,CAAC,YAAY,CAAC;IACnB,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,GAAG,YAAY,CAAC,CAAC;IACnD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,EAAE,QAAQ,GAAG,YAAY,CAAC,CAAC;IAEnE,IAAI,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAE7C,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,GAAG,KAAK,GAAG,OAAO,CAAC;IACzC,IAAI,GAAG,GAAG,YAAY,CAAC,MAAM;QAAE,OAAO,GAAG,OAAO,GAAG,KAAK,CAAC;IAEzD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,UAAU,CAAC,GAAW;IAC7B,OAAO,GAAG;SACP,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;SACtB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC;SACvB,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,KAAe;IAC1D,mCAAmC;IACnC,IAAI,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAE9B,2CAA2C;IAC3C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,IAAI;YAAE,SAAS;QAEpB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;QAC5D,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,IAAI,OAAO,GAAG,EAAE,IAAI,CAAC,CAAC;QAC/C,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,qBAAqB,CAAC,CAAC;IACxD,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,14 @@
+export interface Config {
+    ARCHIVE_DIR: string;
+    SOURCE_DIR: string;
+    DATABASE_PATH: string;
+    EMBED_SOCKET: string;
+    AUTO_UPDATE: boolean;
+    PYTHON_CMD: string;
+    CHUNK_SIZE: number;
+    CHUNK_OVERLAP: number;
+    EMBEDDING_MODEL: string;
+    EMBEDDING_DIM: number;
+}
+export declare function getConfig(): Config;
+export declare function validateConfig(config: Config): string[];

package/dist/config.js

@@ -0,0 +1,52 @@
+import { existsSync } from 'fs';
+const defaults = {
+    ARCHIVE_DIR: './archive',
+    SOURCE_DIR: './source',
+    DATABASE_PATH: './search.db',
+    EMBED_SOCKET: '/tmp/qwen3-embed.sock',
+    AUTO_UPDATE: true,
+    PYTHON_CMD: 'python3',
+    CHUNK_SIZE: 300,
+    CHUNK_OVERLAP: 50,
+    EMBEDDING_MODEL: 'qwen3-small',
+    EMBEDDING_DIM: 1024,
+};
+// Helper to parse integer env vars with NaN fallback to default
+function parseIntOrDefault(envValue, defaultValue) {
+    if (envValue === undefined)
+        return defaultValue;
+    const parsed = parseInt(envValue, 10);
+    return Number.isNaN(parsed) ? defaultValue : parsed;
+}
+export function getConfig() {
+    return {
+        ARCHIVE_DIR: process.env.ARCHIVE_DIR || defaults.ARCHIVE_DIR,
+        SOURCE_DIR: process.env.SOURCE_DIR || defaults.SOURCE_DIR,
+        DATABASE_PATH: process.env.DATABASE_PATH || defaults.DATABASE_PATH,
+        EMBED_SOCKET: process.env.EMBED_SOCKET || defaults.EMBED_SOCKET,
+        // AUTO_UPDATE is enabled by default; only explicitly setting to 'false' disables it
+        AUTO_UPDATE: process.env.AUTO_UPDATE !== 'false',
+        PYTHON_CMD: process.env.PYTHON_CMD || defaults.PYTHON_CMD,
+        CHUNK_SIZE: parseIntOrDefault(process.env.CHUNK_SIZE, defaults.CHUNK_SIZE),
+        CHUNK_OVERLAP: parseIntOrDefault(process.env.CHUNK_OVERLAP, defaults.CHUNK_OVERLAP),
+        EMBEDDING_MODEL: process.env.EMBEDDING_MODEL || defaults.EMBEDDING_MODEL,
+        EMBEDDING_DIM: parseIntOrDefault(process.env.EMBEDDING_DIM, defaults.EMBEDDING_DIM),
+    };
+}
+export function validateConfig(config) {
+    const errors = [];
+    if (!existsSync(config.ARCHIVE_DIR)) {
+        errors.push(`ARCHIVE_DIR does not exist: ${config.ARCHIVE_DIR}`);
+    }
+    if (!existsSync(config.SOURCE_DIR)) {
+        errors.push(`SOURCE_DIR does not exist: ${config.SOURCE_DIR}`);
+    }
+    if (config.CHUNK_SIZE < 100 || config.CHUNK_SIZE > 1000) {
+        errors.push(`CHUNK_SIZE must be between 100 and 1000: ${config.CHUNK_SIZE}`);
+    }
+    if (config.CHUNK_OVERLAP < 0 || config.CHUNK_OVERLAP >= config.CHUNK_SIZE) {
+        errors.push(`CHUNK_OVERLAP must be between 0 and CHUNK_SIZE: ${config.CHUNK_OVERLAP}`);
+    }
+    return errors;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAehC,MAAM,QAAQ,GAAW;IACvB,WAAW,EAAE,WAAW;IACxB,UAAU,EAAE,UAAU;IACtB,aAAa,EAAE,aAAa;IAC5B,YAAY,EAAE,uBAAuB;IACrC,WAAW,EAAE,IAAI;IACjB,UAAU,EAAE,SAAS;IACrB,UAAU,EAAE,GAAG;IACf,aAAa,EAAE,EAAE;IACjB,eAAe,EAAE,aAAa;IAC9B,aAAa,EAAE,IAAI;CACpB,CAAC;AAEF,gEAAgE;AAChE,SAAS,iBAAiB,CAAC,QAA4B,EAAE,YAAoB;IAC3E,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,YAAY,CAAC;IAChD,MAAM,MAAM,GAAG,QAAQ,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IACtC,OAAO,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,SAAS;IACvB,OAAO;QACL,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,QAAQ,CAAC,WAAW;QAC5D,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,QAAQ,CAAC,UAAU;QACzD,aAAa,EAAE,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,QAAQ,CAAC,aAAa;QAClE,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,QAAQ,CAAC,YAAY;QAC/D,oFAAoF;QACpF,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,WAAW,KAAK,OAAO;QAChD,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,QAAQ,CAAC,UAAU;QACzD,UAAU,EAAE,iBAAiB,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAC,UAAU,CAAC;QAC1E,aAAa,EAAE,iBAAiB,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,QAAQ,CAAC,aAAa,CAAC;QACnF,eAAe,EAAE,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,QAAQ,CAAC,eAAe;QACxE,aAAa,EAAE,iBAAiB,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,QAAQ,CAAC,aAAa,CAAC;KACpF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;QACpC,MAAM,CAAC,IAAI,CAAC,+BAA+B,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;QACnC,MAAM,CAAC,IAAI,CAAC,8BAA8B,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;IACjE,CAAC;IACD,IAAI,MAAM,CAAC,UAAU,GAAG,GAAG,IAAI,MAAM,CAAC,UAAU,GAAG,IAAI,EAAE,CAAC;QACxD,MAAM,CAAC,IAAI,CAAC,4CAA4C,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;IAC/E,CAAC;IACD,IAAI,MAAM,CAAC,aAAa,GAAG,CAAC,IAAI,MAAM,CAAC,aAAa,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QAC1E,MAAM,CAAC,IAAI,CAAC,mDAAmD,MAAM,CAAC,aAAa,EAAE,CAAC,CAAC;IACzF,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/db/chunks.d.ts

@@ -0,0 +1,14 @@
+export interface Chunk {
+    id?: number;
+    conversation_id: string;
+    chunk_index: number;
+    page_number: number | null;
+    role: 'user' | 'assistant';
+    content: string;
+    embedding: Buffer | null;
+}
+export declare function insertChunk(c: Chunk): number;
+export declare function getChunksForConversation(conversationId: string): Chunk[];
+export declare function searchChunksFTS(query: string, limit?: number): Chunk[];
+export declare function sanitizeFTSQuery(query: string): string;
+export declare function deleteChunksForConversation(conversationId: string): void;

package/dist/db/chunks.js

@@ -0,0 +1,43 @@
+import { getDatabase } from './index.js';
+export function insertChunk(c) {
+    const result = getDatabase()
+        .prepare(`INSERT INTO chunks
+       (conversation_id, chunk_index, page_number, role, content, embedding)
+       VALUES (?, ?, ?, ?, ?, ?)`)
+        .run(c.conversation_id, c.chunk_index, c.page_number, c.role, c.content, c.embedding);
+    return result.lastInsertRowid;
+}
+export function getChunksForConversation(conversationId) {
+    return getDatabase()
+        .prepare('SELECT * FROM chunks WHERE conversation_id = ? ORDER BY chunk_index')
+        .all(conversationId);
+}
+export function searchChunksFTS(query, limit = 100) {
+    const sanitized = sanitizeFTSQuery(query);
+    if (!sanitized)
+        return [];
+    return getDatabase()
+        .prepare(`SELECT c.* FROM chunks_fts fts
+       JOIN chunks c ON c.id = fts.rowid
+       WHERE chunks_fts MATCH ?
+       ORDER BY bm25(chunks_fts)
+       LIMIT ?`)
+        .all(sanitized, limit);
+}
+export function sanitizeFTSQuery(query) {
+    // Remove FTS5 special characters and operators
+    return query
+        .replace(/["\*\(\)]/g, ' ') // Remove quotes, wildcards, parentheses
+        .replace(/\b(AND|OR|NOT)\b/gi, ' ') // Remove boolean operators
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean)
+        .map((token) => `"${token}"`) // Wrap each token in quotes for exact matching
+        .join(' ');
+}
+export function deleteChunksForConversation(conversationId) {
+    getDatabase()
+        .prepare('DELETE FROM chunks WHERE conversation_id = ?')
+        .run(conversationId);
+}
+//# sourceMappingURL=chunks.js.map

package/dist/db/chunks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunks.js","sourceRoot":"","sources":["../../src/db/chunks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAYzC,MAAM,UAAU,WAAW,CAAC,CAAQ;IAClC,MAAM,MAAM,GAAG,WAAW,EAAE;SACzB,OAAO,CACN;;iCAE2B,CAC5B;SACA,GAAG,CAAC,CAAC,CAAC,eAAe,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC;IACxF,OAAO,MAAM,CAAC,eAAyB,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,cAAsB;IAC7D,OAAO,WAAW,EAAE;SACjB,OAAO,CAAC,qEAAqE,CAAC;SAC9E,GAAG,CAAC,cAAc,CAAY,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAa,EAAE,KAAK,GAAG,GAAG;IACxD,MAAM,SAAS,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAC1C,IAAI,CAAC,SAAS;QAAE,OAAO,EAAE,CAAC;IAE1B,OAAO,WAAW,EAAE;SACjB,OAAO,CACN;;;;eAIS,CACV;SACA,GAAG,CAAC,SAAS,EAAE,KAAK,CAAY,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,+CAA+C;IAC/C,OAAO,KAAK;SACT,OAAO,CAAC,YAAY,EAAE,GAAG,CAAC,CAAW,wCAAwC;SAC7E,OAAO,CAAC,oBAAoB,EAAE,GAAG,CAAC,CAAG,2BAA2B;SAChE,IAAI,EAAE;SACN,KAAK,CAAC,KAAK,CAAC;SACZ,MAAM,CAAC,OAAO,CAAC;SACf,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,KAAK,GAAG,CAAC,CAAU,+CAA+C;SACrF,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,cAAsB;IAChE,WAAW,EAAE;SACV,OAAO,CAAC,8CAA8C,CAAC;SACvD,GAAG,CAAC,cAAc,CAAC,CAAC;AACzB,CAAC"}

package/dist/db/conversations.d.ts

@@ -0,0 +1,16 @@
+export interface Conversation {
+    id: string;
+    project: string;
+    title: string | null;
+    created_at: string | null;
+    file_path: string;
+    content_hash: string;
+    source_mtime: number;
+    indexed_at?: string;
+}
+export declare function insertConversation(c: Conversation): void;
+export declare function getConversation(id: string): Conversation | null;
+export declare function getConversationByPath(path: string): Conversation | null;
+export declare function deleteConversation(id: string): void;
+export declare function listConversations(project?: string): Conversation[];
+export declare function getRecentConversations(limit?: number): Conversation[];