@tobilu/qmd 0.9.0

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@tobilu/qmd",
+  "version": "0.9.0",
+  "description": "Query Markup Documents - On-device hybrid search for markdown files with BM25, vector search, and LLM reranking",
+  "type": "module",
+  "bin": {
+    "qmd": "./qmd"
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "!src/test-preload.ts",
+    "qmd",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "bun test --preload ./src/test-preload.ts",
+    "qmd": "bun src/qmd.ts",
+    "index": "bun src/qmd.ts index",
+    "vector": "bun src/qmd.ts vector",
+    "search": "bun src/qmd.ts search",
+    "vsearch": "bun src/qmd.ts vsearch",
+    "rerank": "bun src/qmd.ts rerank",
+    "link": "bun link",
+    "inspector": "npx @modelcontextprotocol/inspector bun src/qmd.ts mcp",
+    "release": "./scripts/release.sh"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tobi/qmd.git"
+  },
+  "homepage": "https://github.com/tobi/qmd#readme",
+  "bugs": {
+    "url": "https://github.com/tobi/qmd/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.1",
+    "node-llama-cpp": "^3.14.5",
+    "sqlite-vec": "^0.1.7-alpha.2",
+    "yaml": "^2.8.2",
+    "zod": "^4.2.1"
+  },
+  "optionalDependencies": {
+    "sqlite-vec-darwin-arm64": "^0.1.7-alpha.2",
+    "sqlite-vec-darwin-x64": "^0.1.7-alpha.2",
+    "sqlite-vec-linux-x64": "^0.1.7-alpha.2",
+    "sqlite-vec-win32-x64": "^0.1.7-alpha.2"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "keywords": [
+    "markdown",
+    "search",
+    "fts",
+    "full-text-search",
+    "vector",
+    "semantic-search",
+    "sqlite",
+    "bm25",
+    "embeddings",
+    "rag",
+    "mcp",
+    "reranking",
+    "knowledge-base",
+    "local-ai",
+    "llm"
+  ],
+  "license": "MIT"
+}

package/qmd

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# qmd - Quick Markdown Search
+set -euo pipefail
+
+# Find bun - prefer PATH, fallback to known locations
+find_bun() {
+  # First: check if bun is in PATH and modern enough
+  if command -v bun &>/dev/null; then
+    local ver=$(bun --version 2>/dev/null || echo "0")
+    if [[ "$ver" =~ ^1\. ]]; then
+      command -v bun
+      return 0
+    fi
+  fi
+
+  # Fallback: derive paths (need HOME)
+  : "${HOME:=$(eval echo ~)}"
+
+  # If running from .bun tree, use that bun
+  if [[ "${BASH_SOURCE[0]}" == */.bun/* ]]; then
+    local bun_home="${BASH_SOURCE[0]%%/.bun/*}/.bun"
+    if [[ -x "$bun_home/bin/bun" ]]; then
+      echo "$bun_home/bin/bun"
+      return 0
+    fi
+  fi
+
+  # Check known locations
+  local candidates=(
+    "$HOME/.local/share/mise/installs/bun/latest/bin/bun"
+    "$HOME/.local/share/mise/shims/bun"
+    "$HOME/.asdf/shims/bun"
+    "/opt/homebrew/bin/bun"
+    "/usr/local/bin/bun"
+    "$HOME/.bun/bin/bun"
+  )
+  for c in "${candidates[@]}"; do
+    [[ -x "$c" ]] && { echo "$c"; return 0; }
+  done
+
+  return 1
+}
+
+BUN=$(find_bun) || { echo "Error: bun not found. Install from https://bun.sh" >&2; exit 1; }
+
+# Resolve symlinks to find script location
+SOURCE="${BASH_SOURCE[0]}"
+while [[ -L "$SOURCE" ]]; do
+  DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+  SOURCE="$(readlink "$SOURCE")"
+  [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+SCRIPT_DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+
+exec "$BUN" "$SCRIPT_DIR/src/qmd.ts" "$@"

package/src/collections.ts

@@ -0,0 +1,390 @@
+/**
+ * Collections configuration management
+ *
+ * This module manages the YAML-based collection configuration at ~/.config/qmd/index.yml.
+ * Collections define which directories to index and their associated contexts.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import YAML from "yaml";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Context definitions for a collection
+ * Key is path prefix (e.g., "/", "/2024", "/Board of Directors")
+ * Value is the context description
+ */
+export type ContextMap = Record<string, string>;
+
+/**
+ * A single collection configuration
+ */
+export interface Collection {
+  path: string;           // Absolute path to index
+  pattern: string;        // Glob pattern (e.g., "**/*.md")
+  context?: ContextMap;   // Optional context definitions
+  update?: string;        // Optional bash command to run during qmd update
+}
+
+/**
+ * The complete configuration file structure
+ */
+export interface CollectionConfig {
+  global_context?: string;                    // Context applied to all collections
+  collections: Record<string, Collection>;    // Collection name -> config
+}
+
+/**
+ * Collection with its name (for return values)
+ */
+export interface NamedCollection extends Collection {
+  name: string;
+}
+
+// ============================================================================
+// Configuration paths
+// ============================================================================
+
+// Current index name (default: "index")
+let currentIndexName: string = "index";
+
+/**
+ * Set the current index name for config file lookup
+ * Config file will be ~/.config/qmd/{indexName}.yml
+ */
+export function setConfigIndexName(name: string): void {
+  currentIndexName = name;
+}
+
+function getConfigDir(): string {
+  // Allow override via QMD_CONFIG_DIR for testing
+  if (process.env.QMD_CONFIG_DIR) {
+    return process.env.QMD_CONFIG_DIR;
+  }
+  return join(homedir(), ".config", "qmd");
+}
+
+function getConfigFilePath(): string {
+  return join(getConfigDir(), `${currentIndexName}.yml`);
+}
+
+/**
+ * Ensure config directory exists
+ */
+function ensureConfigDir(): void {
+  const configDir = getConfigDir();
+  if (!existsSync(configDir)) {
+    mkdirSync(configDir, { recursive: true });
+  }
+}
+
+// ============================================================================
+// Core functions
+// ============================================================================
+
+/**
+ * Load configuration from ~/.config/qmd/index.yml
+ * Returns empty config if file doesn't exist
+ */
+export function loadConfig(): CollectionConfig {
+  const configPath = getConfigFilePath();
+  if (!existsSync(configPath)) {
+    return { collections: {} };
+  }
+
+  try {
+    const content = readFileSync(configPath, "utf-8");
+    const config = YAML.parse(content) as CollectionConfig;
+
+    // Ensure collections object exists
+    if (!config.collections) {
+      config.collections = {};
+    }
+
+    return config;
+  } catch (error) {
+    throw new Error(`Failed to parse ${configPath}: ${error}`);
+  }
+}
+
+/**
+ * Save configuration to ~/.config/qmd/index.yml
+ */
+export function saveConfig(config: CollectionConfig): void {
+  ensureConfigDir();
+  const configPath = getConfigFilePath();
+
+  try {
+    const yaml = YAML.stringify(config, {
+      indent: 2,
+      lineWidth: 0,  // Don't wrap lines
+    });
+    writeFileSync(configPath, yaml, "utf-8");
+  } catch (error) {
+    throw new Error(`Failed to write ${configPath}: ${error}`);
+  }
+}
+
+/**
+ * Get a specific collection by name
+ * Returns null if not found
+ */
+export function getCollection(name: string): NamedCollection | null {
+  const config = loadConfig();
+  const collection = config.collections[name];
+
+  if (!collection) {
+    return null;
+  }
+
+  return { name, ...collection };
+}
+
+/**
+ * List all collections
+ */
+export function listCollections(): NamedCollection[] {
+  const config = loadConfig();
+  return Object.entries(config.collections).map(([name, collection]) => ({
+    name,
+    ...collection,
+  }));
+}
+
+/**
+ * Add or update a collection
+ */
+export function addCollection(
+  name: string,
+  path: string,
+  pattern: string = "**/*.md"
+): void {
+  const config = loadConfig();
+
+  config.collections[name] = {
+    path,
+    pattern,
+    context: config.collections[name]?.context, // Preserve existing context
+  };
+
+  saveConfig(config);
+}
+
+/**
+ * Remove a collection
+ */
+export function removeCollection(name: string): boolean {
+  const config = loadConfig();
+
+  if (!config.collections[name]) {
+    return false;
+  }
+
+  delete config.collections[name];
+  saveConfig(config);
+  return true;
+}
+
+/**
+ * Rename a collection
+ */
+export function renameCollection(oldName: string, newName: string): boolean {
+  const config = loadConfig();
+
+  if (!config.collections[oldName]) {
+    return false;
+  }
+
+  if (config.collections[newName]) {
+    throw new Error(`Collection '${newName}' already exists`);
+  }
+
+  config.collections[newName] = config.collections[oldName];
+  delete config.collections[oldName];
+  saveConfig(config);
+  return true;
+}
+
+// ============================================================================
+// Context management
+// ============================================================================
+
+/**
+ * Get global context
+ */
+export function getGlobalContext(): string | undefined {
+  const config = loadConfig();
+  return config.global_context;
+}
+
+/**
+ * Set global context
+ */
+export function setGlobalContext(context: string | undefined): void {
+  const config = loadConfig();
+  config.global_context = context;
+  saveConfig(config);
+}
+
+/**
+ * Get all contexts for a collection
+ */
+export function getContexts(collectionName: string): ContextMap | undefined {
+  const collection = getCollection(collectionName);
+  return collection?.context;
+}
+
+/**
+ * Add or update a context for a specific path in a collection
+ */
+export function addContext(
+  collectionName: string,
+  pathPrefix: string,
+  contextText: string
+): boolean {
+  const config = loadConfig();
+  const collection = config.collections[collectionName];
+
+  if (!collection) {
+    return false;
+  }
+
+  if (!collection.context) {
+    collection.context = {};
+  }
+
+  collection.context[pathPrefix] = contextText;
+  saveConfig(config);
+  return true;
+}
+
+/**
+ * Remove a context from a collection
+ */
+export function removeContext(
+  collectionName: string,
+  pathPrefix: string
+): boolean {
+  const config = loadConfig();
+  const collection = config.collections[collectionName];
+
+  if (!collection?.context?.[pathPrefix]) {
+    return false;
+  }
+
+  delete collection.context[pathPrefix];
+
+  // Remove empty context object
+  if (Object.keys(collection.context).length === 0) {
+    delete collection.context;
+  }
+
+  saveConfig(config);
+  return true;
+}
+
+/**
+ * List all contexts across all collections
+ */
+export function listAllContexts(): Array<{
+  collection: string;
+  path: string;
+  context: string;
+}> {
+  const config = loadConfig();
+  const results: Array<{ collection: string; path: string; context: string }> = [];
+
+  // Add global context if present
+  if (config.global_context) {
+    results.push({
+      collection: "*",
+      path: "/",
+      context: config.global_context,
+    });
+  }
+
+  // Add collection contexts
+  for (const [name, collection] of Object.entries(config.collections)) {
+    if (collection.context) {
+      for (const [path, context] of Object.entries(collection.context)) {
+        results.push({
+          collection: name,
+          path,
+          context,
+        });
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Find best matching context for a given collection and path
+ * Returns the most specific matching context (longest path prefix match)
+ */
+export function findContextForPath(
+  collectionName: string,
+  filePath: string
+): string | undefined {
+  const config = loadConfig();
+  const collection = config.collections[collectionName];
+
+  if (!collection?.context) {
+    return config.global_context;
+  }
+
+  // Find all matching prefixes
+  const matches: Array<{ prefix: string; context: string }> = [];
+
+  for (const [prefix, context] of Object.entries(collection.context)) {
+    // Normalize paths for comparison
+    const normalizedPath = filePath.startsWith("/") ? filePath : `/${filePath}`;
+    const normalizedPrefix = prefix.startsWith("/") ? prefix : `/${prefix}`;
+
+    if (normalizedPath.startsWith(normalizedPrefix)) {
+      matches.push({ prefix: normalizedPrefix, context });
+    }
+  }
+
+  // Return most specific match (longest prefix)
+  if (matches.length > 0) {
+    matches.sort((a, b) => b.prefix.length - a.prefix.length);
+    return matches[0]!.context;
+  }
+
+  // Fallback to global context
+  return config.global_context;
+}
+
+// ============================================================================
+// Utility functions
+// ============================================================================
+
+/**
+ * Get the config file path (useful for error messages)
+ */
+export function getConfigPath(): string {
+  return getConfigFilePath();
+}
+
+/**
+ * Check if config file exists
+ */
+export function configExists(): boolean {
+  return existsSync(getConfigFilePath());
+}
+
+/**
+ * Validate a collection name
+ * Collection names must be valid and not contain special characters
+ */
+export function isValidCollectionName(name: string): boolean {
+  // Allow alphanumeric, hyphens, underscores
+  return /^[a-zA-Z0-9_-]+$/.test(name);
+}