@tobilu/qmd 0.9.0 → 1.0.5

package/dist/collections.js

@@ -0,0 +1,282 @@
+/**
+ * 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";
+// ============================================================================
+// Configuration paths
+// ============================================================================
+// Current index name (default: "index")
+let currentIndexName = "index";
+/**
+ * Set the current index name for config file lookup
+ * Config file will be ~/.config/qmd/{indexName}.yml
+ */
+export function setConfigIndexName(name) {
+    currentIndexName = name;
+}
+function getConfigDir() {
+    // 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() {
+    return join(getConfigDir(), `${currentIndexName}.yml`);
+}
+/**
+ * Ensure config directory exists
+ */
+function ensureConfigDir() {
+    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() {
+    const configPath = getConfigFilePath();
+    if (!existsSync(configPath)) {
+        return { collections: {} };
+    }
+    try {
+        const content = readFileSync(configPath, "utf-8");
+        const config = YAML.parse(content);
+        // 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) {
+    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) {
+    const config = loadConfig();
+    const collection = config.collections[name];
+    if (!collection) {
+        return null;
+    }
+    return { name, ...collection };
+}
+/**
+ * List all collections
+ */
+export function listCollections() {
+    const config = loadConfig();
+    return Object.entries(config.collections).map(([name, collection]) => ({
+        name,
+        ...collection,
+    }));
+}
+/**
+ * Add or update a collection
+ */
+export function addCollection(name, path, pattern = "**/*.md") {
+    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) {
+    const config = loadConfig();
+    if (!config.collections[name]) {
+        return false;
+    }
+    delete config.collections[name];
+    saveConfig(config);
+    return true;
+}
+/**
+ * Rename a collection
+ */
+export function renameCollection(oldName, newName) {
+    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() {
+    const config = loadConfig();
+    return config.global_context;
+}
+/**
+ * Set global context
+ */
+export function setGlobalContext(context) {
+    const config = loadConfig();
+    config.global_context = context;
+    saveConfig(config);
+}
+/**
+ * Get all contexts for a collection
+ */
+export function getContexts(collectionName) {
+    const collection = getCollection(collectionName);
+    return collection?.context;
+}
+/**
+ * Add or update a context for a specific path in a collection
+ */
+export function addContext(collectionName, pathPrefix, contextText) {
+    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, pathPrefix) {
+    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() {
+    const config = loadConfig();
+    const results = [];
+    // 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, filePath) {
+    const config = loadConfig();
+    const collection = config.collections[collectionName];
+    if (!collection?.context) {
+        return config.global_context;
+    }
+    // Find all matching prefixes
+    const matches = [];
+    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() {
+    return getConfigFilePath();
+}
+/**
+ * Check if config file exists
+ */
+export function configExists() {
+    return existsSync(getConfigFilePath());
+}
+/**
+ * Validate a collection name
+ * Collection names must be valid and not contain special characters
+ */
+export function isValidCollectionName(name) {
+    // Allow alphanumeric, hyphens, underscores
+    return /^[a-zA-Z0-9_-]+$/.test(name);
+}

package/dist/db.d.ts

@@ -0,0 +1,33 @@
+/**
+ * db.ts - Cross-runtime SQLite compatibility layer
+ *
+ * Provides a unified Database export that works under both Bun (bun:sqlite)
+ * and Node.js (better-sqlite3). The APIs are nearly identical — the main
+ * difference is the import path.
+ */
+export declare const isBun: boolean;
+/**
+ * Open a SQLite database. Works with both bun:sqlite and better-sqlite3.
+ */
+export declare function openDatabase(path: string): Database;
+/**
+ * Common subset of the Database interface used throughout QMD.
+ */
+export interface Database {
+    exec(sql: string): void;
+    prepare(sql: string): Statement;
+    loadExtension(path: string): void;
+    close(): void;
+}
+export interface Statement {
+    run(...params: any[]): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+    get(...params: any[]): any;
+    all(...params: any[]): any[];
+}
+/**
+ * Load the sqlite-vec extension into a database.
+ */
+export declare function loadSqliteVec(db: Database): void;

package/dist/db.js

@@ -0,0 +1,34 @@
+/**
+ * db.ts - Cross-runtime SQLite compatibility layer
+ *
+ * Provides a unified Database export that works under both Bun (bun:sqlite)
+ * and Node.js (better-sqlite3). The APIs are nearly identical — the main
+ * difference is the import path.
+ */
+export const isBun = typeof globalThis.Bun !== "undefined";
+let _Database;
+let _sqliteVecLoad;
+if (isBun) {
+    // Dynamic string prevents tsc from resolving bun:sqlite on Node.js builds
+    const bunSqlite = "bun:" + "sqlite";
+    _Database = (await import(/* @vite-ignore */ bunSqlite)).Database;
+    const { getLoadablePath } = await import("sqlite-vec");
+    _sqliteVecLoad = (db) => db.loadExtension(getLoadablePath());
+}
+else {
+    _Database = (await import("better-sqlite3")).default;
+    const sqliteVec = await import("sqlite-vec");
+    _sqliteVecLoad = (db) => sqliteVec.load(db);
+}
+/**
+ * Open a SQLite database. Works with both bun:sqlite and better-sqlite3.
+ */
+export function openDatabase(path) {
+    return new _Database(path);
+}
+/**
+ * Load the sqlite-vec extension into a database.
+ */
+export function loadSqliteVec(db) {
+    _sqliteVecLoad(db);
+}

package/dist/formatter.d.ts

@@ -0,0 +1,119 @@
+/**
+ * formatter.ts - Output formatting utilities for QMD
+ *
+ * Provides methods to format search results and documents into various output formats:
+ * JSON, CSV, XML, Markdown, files list, and CLI (colored terminal output).
+ */
+import type { SearchResult, MultiGetResult, DocumentResult } from "./store.js";
+export type { SearchResult, MultiGetResult, DocumentResult };
+export type MultiGetFile = {
+    filepath: string;
+    displayPath: string;
+    title: string;
+    body: string;
+    context?: string | null;
+    skipped: false;
+} | {
+    filepath: string;
+    displayPath: string;
+    title: string;
+    body: string;
+    context?: string | null;
+    skipped: true;
+    skipReason: string;
+};
+export type OutputFormat = "cli" | "csv" | "md" | "xml" | "files" | "json";
+export type FormatOptions = {
+    full?: boolean;
+    query?: string;
+    useColor?: boolean;
+    lineNumbers?: boolean;
+};
+/**
+ * Add line numbers to text content.
+ * Each line becomes: "{lineNum}: {content}"
+ * @param text The text to add line numbers to
+ * @param startLine Optional starting line number (default: 1)
+ */
+export declare function addLineNumbers(text: string, startLine?: number): string;
+/**
+ * Extract short docid from a full hash (first 6 characters).
+ */
+export declare function getDocid(hash: string): string;
+export declare function escapeCSV(value: string | null | number): string;
+export declare function escapeXml(str: string): string;
+/**
+ * Format search results as JSON
+ */
+export declare function searchResultsToJson(results: SearchResult[], opts?: FormatOptions): string;
+/**
+ * Format search results as CSV
+ */
+export declare function searchResultsToCsv(results: SearchResult[], opts?: FormatOptions): string;
+/**
+ * Format search results as simple files list (docid,score,filepath,context)
+ */
+export declare function searchResultsToFiles(results: SearchResult[]): string;
+/**
+ * Format search results as Markdown
+ */
+export declare function searchResultsToMarkdown(results: SearchResult[], opts?: FormatOptions): string;
+/**
+ * Format search results as XML
+ */
+export declare function searchResultsToXml(results: SearchResult[], opts?: FormatOptions): string;
+/**
+ * Format search results for MCP (simpler CSV format with pre-extracted snippets)
+ */
+export declare function searchResultsToMcpCsv(results: {
+    docid: string;
+    file: string;
+    title: string;
+    score: number;
+    context: string | null;
+    snippet: string;
+}[]): string;
+/**
+ * Format documents as JSON
+ */
+export declare function documentsToJson(results: MultiGetFile[]): string;
+/**
+ * Format documents as CSV
+ */
+export declare function documentsToCsv(results: MultiGetFile[]): string;
+/**
+ * Format documents as files list
+ */
+export declare function documentsToFiles(results: MultiGetFile[]): string;
+/**
+ * Format documents as Markdown
+ */
+export declare function documentsToMarkdown(results: MultiGetFile[]): string;
+/**
+ * Format documents as XML
+ */
+export declare function documentsToXml(results: MultiGetFile[]): string;
+/**
+ * Format a single DocumentResult as JSON
+ */
+export declare function documentToJson(doc: DocumentResult): string;
+/**
+ * Format a single DocumentResult as Markdown
+ */
+export declare function documentToMarkdown(doc: DocumentResult): string;
+/**
+ * Format a single DocumentResult as XML
+ */
+export declare function documentToXml(doc: DocumentResult): string;
+/**
+ * Format a single document to the specified format
+ */
+export declare function formatDocument(doc: DocumentResult, format: OutputFormat): string;
+/**
+ * Format search results to the specified output format
+ */
+export declare function formatSearchResults(results: SearchResult[], format: OutputFormat, opts?: FormatOptions): string;
+/**
+ * Format documents to the specified output format
+ */
+export declare function formatDocuments(results: MultiGetFile[], format: OutputFormat): string;