@ncukondo/reference-manager 0.1.0 → 0.4.0

package/dist/chunks/{detector-BF8Mcc72.js → file-watcher-B-SiUw5f.js}

@@ -1,10 +1,12 @@
 import { randomUUID, createHash } from "node:crypto";
-import { createReadStream, existsSync, readFileSync } from "node:fs";
+import { createReadStream } from "node:fs";
+import * as fs from "node:fs/promises";
 import { readFile, mkdir, writeFile } from "node:fs/promises";
 import { z } from "zod";
-import { dirname, join } from "node:path";
-import { parse } from "@iarna/toml";
-import { tmpdir, homedir } from "node:os";
+import * as path from "node:path";
+import { dirname } from "node:path";
+import { EventEmitter } from "node:events";
+import chokidar from "chokidar";
 function normalizeText(text) {
   return text.toLowerCase().replace(/\s+/g, "_").replace(/[^a-z0-9_]/g, "").replace(/_+/g, "_").replace(/^_|_$/g, "");
 }
@@ -310,12 +312,18 @@ const CslDateSchema = z.object({
   circa: z.boolean().optional(),
   literal: z.string().optional()
 });
+const CslFulltextSchema = z.object({
+  pdf: z.string().optional(),
+  markdown: z.string().optional()
+});
 const CslCustomSchema = z.object({
   uuid: z.string(),
   created_at: z.string(),
   timestamp: z.string(),
-  additional_urls: z.array(z.string()).optional()
-});
+  additional_urls: z.array(z.string()).optional(),
+  fulltext: CslFulltextSchema.optional(),
+  tags: z.array(z.string()).optional()
+}).passthrough();
 const CslItemSchema = z.object({
   id: z.string(),
   type: z.string(),
@@ -449,46 +457,83 @@ class Library {
     await writeCslJson(this.filePath, items);
     this.currentHash = await computeFileHash(this.filePath);
   }
+  /**
+   * Reloads the library from file if it was modified externally.
+   * Self-writes (detected via hash comparison) are skipped.
+   * @returns true if reload occurred, false if skipped (self-write detected)
+   */
+  async reload() {
+    const newHash = await computeFileHash(this.filePath);
+    if (newHash === this.currentHash) {
+      return false;
+    }
+    const items = await parseCslJson(this.filePath);
+    this.references = [];
+    this.uuidIndex.clear();
+    this.idIndex.clear();
+    this.doiIndex.clear();
+    this.pmidIndex.clear();
+    for (const item of items) {
+      const ref = new Reference(item);
+      this.references.push(ref);
+      this.addToIndices(ref);
+    }
+    this.currentHash = newHash;
+    return true;
+  }
   /**
    * Add a reference to the library
+   * @param item - The CSL item to add
+   * @returns The added CSL item (with generated ID and UUID)
    */
-  add(item) {
+  async add(item) {
     const existingIds = new Set(this.references.map((ref2) => ref2.getId()));
     const ref = Reference.create(item, { existingIds });
     this.references.push(ref);
     this.addToIndices(ref);
+    return ref.getItem();
   }
   /**
-   * Remove a reference by UUID
+   * Remove a reference by citation ID or UUID.
+   * @param identifier - The citation ID or UUID of the reference to remove
+   * @param options - Remove options (byUuid to use UUID lookup)
+   * @returns Remove result with removed status and the removed item
    */
-  removeByUuid(uuid) {
-    const ref = this.uuidIndex.get(uuid);
+  async remove(identifier, options = {}) {
+    const { byUuid = false } = options;
+    const ref = byUuid ? this.uuidIndex.get(identifier) : this.idIndex.get(identifier);
     if (!ref) {
-      return false;
+      return { removed: false };
     }
-    return this.removeReference(ref);
+    const removedItem = ref.getItem();
+    const removed = this.removeReference(ref);
+    return { removed, removedItem };
   }
   /**
-   * Remove a reference by ID
+   * Update a reference by citation ID or UUID.
+   * @param identifier - The citation ID or UUID of the reference to update
+   * @param updates - Partial updates to apply to the reference
+   * @param options - Update options (byUuid to use UUID lookup, onIdCollision for collision handling)
+   * @returns Update result with updated item, success status, and any ID changes
    */
-  removeById(id) {
-    const ref = this.idIndex.get(id);
+  async update(identifier, updates, options = {}) {
+    const { byUuid = false, ...updateOptions } = options;
+    const ref = byUuid ? this.uuidIndex.get(identifier) : this.idIndex.get(identifier);
     if (!ref) {
-      return false;
+      return { updated: false };
     }
-    return this.removeReference(ref);
-  }
-  /**
-   * Find a reference by UUID
-   */
-  findByUuid(uuid) {
-    return this.uuidIndex.get(uuid);
+    return this.updateReference(ref, updates, updateOptions);
   }
   /**
-   * Find a reference by ID
+   * Find a reference by citation ID or UUID.
+   * @param identifier - The citation ID or UUID of the reference to find
+   * @param options - Find options (byUuid to use UUID lookup)
+   * @returns The CSL item if found, undefined otherwise
    */
-  findById(id) {
-    return this.idIndex.get(id);
+  async find(identifier, options = {}) {
+    const { byUuid = false } = options;
+    const ref = byUuid ? this.uuidIndex.get(identifier) : this.idIndex.get(identifier);
+    return ref?.getItem();
   }
   /**
    * Find a reference by DOI
@@ -505,8 +550,8 @@ class Library {
   /**
    * Get all references
    */
-  getAll() {
-    return [...this.references];
+  async getAll() {
+    return this.references.map((ref) => ref.getItem());
   }
   /**
    * Get the file path
@@ -545,281 +590,122 @@ class Library {
       return false;
     }
     this.references.splice(index, 1);
-    this.uuidIndex.delete(ref.getUuid());
-    this.idIndex.delete(ref.getId());
-    const doi = ref.getDoi();
-    if (doi) {
-      this.doiIndex.delete(doi);
-    }
-    const pmid = ref.getPmid();
-    if (pmid) {
-      this.pmidIndex.delete(pmid);
-    }
+    this.removeFromIndices(ref);
     return true;
   }
-}
-const logLevelSchema = z.enum(["silent", "info", "debug"]);
-const backupConfigSchema = z.object({
-  maxGenerations: z.number().int().positive(),
-  maxAgeDays: z.number().int().positive(),
-  directory: z.string().min(1)
-});
-const watchConfigSchema = z.object({
-  enabled: z.boolean(),
-  debounceMs: z.number().int().nonnegative(),
-  pollIntervalMs: z.number().int().positive(),
-  retryIntervalMs: z.number().int().positive(),
-  maxRetries: z.number().int().nonnegative()
-});
-const serverConfigSchema = z.object({
-  autoStart: z.boolean(),
-  autoStopMinutes: z.number().int().nonnegative()
-});
-const configSchema = z.object({
-  library: z.string().min(1),
-  logLevel: logLevelSchema,
-  backup: backupConfigSchema,
-  watch: watchConfigSchema,
-  server: serverConfigSchema
-});
-const partialConfigSchema = z.object({
-  library: z.string().min(1).optional(),
-  logLevel: logLevelSchema.optional(),
-  log_level: logLevelSchema.optional(),
-  // snake_case support
-  backup: z.object({
-    maxGenerations: z.number().int().positive().optional(),
-    max_generations: z.number().int().positive().optional(),
-    maxAgeDays: z.number().int().positive().optional(),
-    max_age_days: z.number().int().positive().optional(),
-    directory: z.string().min(1).optional()
-  }).optional(),
-  watch: z.object({
-    enabled: z.boolean().optional(),
-    debounceMs: z.number().int().nonnegative().optional(),
-    debounce_ms: z.number().int().nonnegative().optional(),
-    pollIntervalMs: z.number().int().positive().optional(),
-    poll_interval_ms: z.number().int().positive().optional(),
-    retryIntervalMs: z.number().int().positive().optional(),
-    retry_interval_ms: z.number().int().positive().optional(),
-    maxRetries: z.number().int().nonnegative().optional(),
-    max_retries: z.number().int().nonnegative().optional()
-  }).optional(),
-  server: z.object({
-    autoStart: z.boolean().optional(),
-    auto_start: z.boolean().optional(),
-    autoStopMinutes: z.number().int().nonnegative().optional(),
-    auto_stop_minutes: z.number().int().nonnegative().optional()
-  }).optional()
-}).passthrough();
-function normalizeBackupConfig(backup) {
-  const normalized = {};
-  const maxGenerations = backup.maxGenerations ?? backup.max_generations;
-  if (maxGenerations !== void 0) {
-    normalized.maxGenerations = maxGenerations;
-  }
-  const maxAgeDays = backup.maxAgeDays ?? backup.max_age_days;
-  if (maxAgeDays !== void 0) {
-    normalized.maxAgeDays = maxAgeDays;
-  }
-  if (backup.directory !== void 0) {
-    normalized.directory = backup.directory;
-  }
-  return Object.keys(normalized).length > 0 ? normalized : void 0;
-}
-function normalizeWatchConfig(watch) {
-  const normalized = {};
-  if (watch.enabled !== void 0) {
-    normalized.enabled = watch.enabled;
-  }
-  const debounceMs = watch.debounceMs ?? watch.debounce_ms;
-  if (debounceMs !== void 0) {
-    normalized.debounceMs = debounceMs;
-  }
-  const pollIntervalMs = watch.pollIntervalMs ?? watch.poll_interval_ms;
-  if (pollIntervalMs !== void 0) {
-    normalized.pollIntervalMs = pollIntervalMs;
-  }
-  const retryIntervalMs = watch.retryIntervalMs ?? watch.retry_interval_ms;
-  if (retryIntervalMs !== void 0) {
-    normalized.retryIntervalMs = retryIntervalMs;
-  }
-  const maxRetries = watch.maxRetries ?? watch.max_retries;
-  if (maxRetries !== void 0) {
-    normalized.maxRetries = maxRetries;
-  }
-  return Object.keys(normalized).length > 0 ? normalized : void 0;
-}
-function normalizeServerConfig(server) {
-  const normalized = {};
-  const autoStart = server.autoStart ?? server.auto_start;
-  if (autoStart !== void 0) {
-    normalized.autoStart = autoStart;
-  }
-  const autoStopMinutes = server.autoStopMinutes ?? server.auto_stop_minutes;
-  if (autoStopMinutes !== void 0) {
-    normalized.autoStopMinutes = autoStopMinutes;
-  }
-  return Object.keys(normalized).length > 0 ? normalized : void 0;
-}
-function normalizePartialConfig(partial) {
-  const normalized = {};
-  if (partial.library !== void 0) {
-    normalized.library = partial.library;
-  }
-  const logLevel = partial.logLevel ?? partial.log_level;
-  if (logLevel !== void 0) {
-    normalized.logLevel = logLevel;
-  }
-  if (partial.backup !== void 0) {
-    const backup = normalizeBackupConfig(
-      partial.backup
-    );
-    if (backup) {
-      normalized.backup = backup;
-    }
-  }
-  if (partial.watch !== void 0) {
-    const watch = normalizeWatchConfig(partial.watch);
-    if (watch) {
-      normalized.watch = watch;
+  /**
+   * Update a reference with partial updates.
+   * Preserves uuid and created_at, updates timestamp.
+   */
+  updateReference(ref, updates, options = {}) {
+    const index = this.references.indexOf(ref);
+    if (index === -1) {
+      return { updated: false };
     }
-  }
-  if (partial.server !== void 0) {
-    const server = normalizeServerConfig(
-      partial.server
+    const existingItem = ref.getItem();
+    const currentId = ref.getId();
+    const { newId, idChanged, collision } = this.resolveNewId(
+      updates.id ?? existingItem.id,
+      currentId,
+      options
     );
-    if (server) {
-      normalized.server = server;
+    if (collision) {
+      return { updated: false, idCollision: true };
     }
+    const updatedItem = this.buildUpdatedItem(existingItem, updates, newId);
+    this.removeFromIndices(ref);
+    const newRef = new Reference(updatedItem);
+    this.references[index] = newRef;
+    this.addToIndices(newRef);
+    const result = { updated: true, item: newRef.getItem() };
+    if (idChanged) {
+      result.idChanged = true;
+      result.newId = newId;
+    }
+    return result;
   }
-  return normalized;
-}
-function getDefaultBackupDirectory() {
-  return join(tmpdir(), "reference-manager", "backups");
-}
-function getDefaultLibraryPath() {
-  return join(homedir(), ".reference-manager", "csl.library.json");
-}
-function getDefaultUserConfigPath() {
-  return join(homedir(), ".reference-manager", "config.toml");
-}
-function getDefaultCurrentDirConfigFilename() {
-  return ".reference-manager.config.toml";
-}
-const defaultConfig = {
-  library: getDefaultLibraryPath(),
-  logLevel: "info",
-  backup: {
-    maxGenerations: 50,
-    maxAgeDays: 365,
-    directory: getDefaultBackupDirectory()
-  },
-  watch: {
-    enabled: true,
-    debounceMs: 500,
-    pollIntervalMs: 5e3,
-    retryIntervalMs: 200,
-    maxRetries: 10
-  },
-  server: {
-    autoStart: false,
-    autoStopMinutes: 0
-  }
-};
-function loadTOMLFile(path) {
-  if (!existsSync(path)) {
-    return null;
-  }
-  try {
-    const content = readFileSync(path, "utf-8");
-    const parsed = parse(content);
-    const validated = partialConfigSchema.parse(parsed);
-    return validated;
-  } catch (error) {
-    throw new Error(
-      `Failed to load config from ${path}: ${error instanceof Error ? error.message : String(error)}`
-    );
-  }
-}
-function mergeConfigs(base, ...overrides) {
-  const result = { ...base };
-  for (const override of overrides) {
-    if (!override) continue;
-    if (override.library !== void 0) {
-      result.library = override.library;
+  /**
+   * Resolve the new ID, handling collisions based on options.
+   */
+  resolveNewId(requestedId, currentId, options) {
+    if (requestedId === currentId) {
+      return { newId: requestedId, idChanged: false, collision: false };
     }
-    if (override.logLevel !== void 0) {
-      result.logLevel = override.logLevel;
+    const conflictingRef = this.idIndex.get(requestedId);
+    if (!conflictingRef) {
+      return { newId: requestedId, idChanged: false, collision: false };
     }
-    if (override.backup !== void 0) {
-      result.backup = {
-        ...result.backup,
-        ...override.backup
-      };
+    const onIdCollision = options.onIdCollision ?? "fail";
+    if (onIdCollision === "fail") {
+      return { newId: requestedId, idChanged: false, collision: true };
     }
-    if (override.watch !== void 0) {
-      result.watch = {
-        ...result.watch,
-        ...override.watch
-      };
+    const existingIds = new Set(this.references.map((r) => r.getId()));
+    existingIds.delete(currentId);
+    const resolvedId = this.resolveIdCollision(requestedId, existingIds);
+    return { newId: resolvedId, idChanged: true, collision: false };
+  }
+  /**
+   * Build the updated CslItem, preserving uuid and created_at.
+   */
+  buildUpdatedItem(existingItem, updates, newId) {
+    return {
+      ...existingItem,
+      ...updates,
+      id: newId,
+      type: updates.type ?? existingItem.type,
+      custom: {
+        ...existingItem.custom || {},
+        ...updates.custom || {},
+        uuid: existingItem.custom?.uuid || "",
+        created_at: existingItem.custom?.created_at || (/* @__PURE__ */ new Date()).toISOString(),
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }
+    };
+  }
+  /**
+   * Remove a reference from all indices.
+   */
+  removeFromIndices(ref) {
+    this.uuidIndex.delete(ref.getUuid());
+    this.idIndex.delete(ref.getId());
+    const doi = ref.getDoi();
+    if (doi) {
+      this.doiIndex.delete(doi);
     }
-    if (override.server !== void 0) {
-      result.server = {
-        ...result.server,
-        ...override.server
-      };
+    const pmid = ref.getPmid();
+    if (pmid) {
+      this.pmidIndex.delete(pmid);
     }
   }
-  return result;
-}
-function fillDefaults(partial) {
-  return {
-    library: partial.library ?? defaultConfig.library,
-    logLevel: partial.logLevel ?? defaultConfig.logLevel,
-    backup: {
-      maxGenerations: partial.backup?.maxGenerations ?? defaultConfig.backup.maxGenerations,
-      maxAgeDays: partial.backup?.maxAgeDays ?? defaultConfig.backup.maxAgeDays,
-      directory: partial.backup?.directory ?? defaultConfig.backup.directory
-    },
-    watch: {
-      enabled: partial.watch?.enabled ?? defaultConfig.watch.enabled,
-      debounceMs: partial.watch?.debounceMs ?? defaultConfig.watch.debounceMs,
-      pollIntervalMs: partial.watch?.pollIntervalMs ?? defaultConfig.watch.pollIntervalMs,
-      retryIntervalMs: partial.watch?.retryIntervalMs ?? defaultConfig.watch.retryIntervalMs,
-      maxRetries: partial.watch?.maxRetries ?? defaultConfig.watch.maxRetries
-    },
-    server: {
-      autoStart: partial.server?.autoStart ?? defaultConfig.server.autoStart,
-      autoStopMinutes: partial.server?.autoStopMinutes ?? defaultConfig.server.autoStopMinutes
+  /**
+   * Generate an alphabetic suffix for ID collision resolution.
+   * 0 -> 'a', 1 -> 'b', ..., 25 -> 'z', 26 -> 'aa', etc.
+   */
+  generateSuffix(index) {
+    const alphabet = "abcdefghijklmnopqrstuvwxyz";
+    let suffix = "";
+    let n = index;
+    do {
+      suffix = alphabet[n % 26] + suffix;
+      n = Math.floor(n / 26) - 1;
+    } while (n >= 0);
+    return suffix;
+  }
+  /**
+   * Resolve ID collision by appending alphabetic suffix.
+   */
+  resolveIdCollision(baseId, existingIds) {
+    if (!existingIds.has(baseId)) {
+      return baseId;
     }
-  };
-}
-function loadConfig(options = {}) {
-  const cwd = options.cwd ?? process.cwd();
-  const userConfigPath = options.userConfigPath ?? getDefaultUserConfigPath();
-  const userConfig = loadTOMLFile(userConfigPath);
-  const envConfigPath = process.env.REFERENCE_MANAGER_CONFIG;
-  const envConfig = envConfigPath ? loadTOMLFile(envConfigPath) : null;
-  const currentConfigPath = join(cwd, getDefaultCurrentDirConfigFilename());
-  const currentConfig = loadTOMLFile(currentConfigPath);
-  const normalizedUser = userConfig ? normalizePartialConfig(userConfig) : null;
-  const normalizedEnv = envConfig ? normalizePartialConfig(envConfig) : null;
-  const normalizedCurrent = currentConfig ? normalizePartialConfig(currentConfig) : null;
-  const merged = mergeConfigs(
-    {},
-    normalizedUser,
-    normalizedEnv,
-    normalizedCurrent,
-    options.overrides
-  );
-  const config = fillDefaults(merged);
-  try {
-    return configSchema.parse(config);
-  } catch (error) {
-    throw new Error(
-      `Invalid configuration: ${error instanceof Error ? error.message : String(error)}`
-    );
+    let index = 0;
+    let newId;
+    do {
+      const suffix = this.generateSuffix(index);
+      newId = `${baseId}${suffix}`;
+      index++;
+    } while (existingIds.has(newId));
+    return newId;
   }
 }
 const VALID_FIELDS = /* @__PURE__ */ new Set([
@@ -830,7 +716,8 @@ const VALID_FIELDS = /* @__PURE__ */ new Set([
   "pmid",
   "pmcid",
   "url",
-  "keyword"
+  "keyword",
+  "tag"
 ]);
 function isWhitespace(query, index) {
   return /\s/.test(query.charAt(index));
@@ -993,6 +880,82 @@ function normalize(text) {
   normalized = normalized.replace(/\s+/g, " ").trim();
   return normalized;
 }
+function normalizePreservingCase(text) {
+  let normalized = text.normalize("NFKC");
+  normalized = normalized.normalize("NFD").replace(new RegExp("\\p{M}", "gu"), "");
+  normalized = normalized.replace(/\s+/g, " ").trim();
+  return normalized;
+}
+function hasConsecutiveUppercase(text) {
+  const pattern = /[A-Z]{2,}/;
+  return pattern.test(text);
+}
+function extractUppercaseSegments(text) {
+  const pattern = /[A-Z]{2,}/g;
+  const segments = [];
+  for (const match of text.matchAll(pattern)) {
+    segments.push({
+      segment: match[0],
+      start: match.index,
+      end: match.index + match[0].length
+    });
+  }
+  return segments;
+}
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function normalizeWhitespace(text) {
+  return text.replace(/\s+/g, " ").trim();
+}
+function allUppercaseSegmentsExist(segments, target) {
+  return segments.every((seg) => target.includes(seg.segment));
+}
+function buildMatchPattern(query, segments) {
+  const patternParts = [];
+  let lastEnd = 0;
+  for (const seg of segments) {
+    if (seg.start > lastEnd) {
+      const beforePart = query.slice(lastEnd, seg.start);
+      if (beforePart.trim()) {
+        patternParts.push(escapeRegex(beforePart));
+      }
+    }
+    patternParts.push(`(?:${escapeRegex(seg.segment)})`);
+    lastEnd = seg.end;
+  }
+  if (lastEnd < query.length) {
+    const afterPart = query.slice(lastEnd);
+    if (afterPart.trim()) {
+      patternParts.push(escapeRegex(afterPart));
+    }
+  }
+  return patternParts.join(".*?");
+}
+function matchWithUppercaseSensitivity(query, target) {
+  if (query === "") {
+    return true;
+  }
+  if (target === "") {
+    return false;
+  }
+  const normalizedQuery = normalizeWhitespace(query);
+  const normalizedTarget = normalizeWhitespace(target);
+  if (!hasConsecutiveUppercase(normalizedQuery)) {
+    return normalizedTarget.toLowerCase().includes(normalizedQuery.toLowerCase());
+  }
+  const segments = extractUppercaseSegments(normalizedQuery);
+  if (!allUppercaseSegmentsExist(segments, target)) {
+    return false;
+  }
+  const pattern = buildMatchPattern(normalizedQuery, segments);
+  try {
+    const regex = new RegExp(pattern, "i");
+    return regex.test(normalizedTarget);
+  } catch {
+    return normalizedTarget.toLowerCase().includes(normalizedQuery.toLowerCase());
+  }
+}
 const ID_FIELDS = /* @__PURE__ */ new Set(["DOI", "PMID", "PMCID", "URL"]);
 function extractYear$2(reference) {
   if (reference.issued?.["date-parts"]?.[0]?.[0]) {
@@ -1006,8 +969,8 @@ function extractAuthors(reference) {
   }
   return reference.author.map((author) => {
     const family = author.family || "";
-    const givenInitial = author.given ? author.given[0] : "";
-    return givenInitial ? `${family} ${givenInitial}` : family;
+    const given = author.given || "";
+    return given ? `${family} ${given}` : family;
   }).join(" ");
 }
 function getFieldValue(reference, field) {
@@ -1056,11 +1019,11 @@ function matchKeyword(queryValue, reference) {
   if (!reference.keyword || !Array.isArray(reference.keyword)) {
     return null;
   }
-  const normalizedQuery = normalize(queryValue);
+  const normalizedQuery = normalizePreservingCase(queryValue);
   for (const keyword of reference.keyword) {
     if (typeof keyword === "string") {
-      const normalizedKeyword = normalize(keyword);
-      if (normalizedKeyword.includes(normalizedQuery)) {
+      const normalizedKeyword = normalizePreservingCase(keyword);
+      if (matchWithUppercaseSensitivity(normalizedQuery, normalizedKeyword)) {
         return {
           field: "keyword",
           strength: "partial",
@@ -1071,6 +1034,25 @@ function matchKeyword(queryValue, reference) {
   }
   return null;
 }
+function matchTag(queryValue, reference) {
+  if (!reference.custom?.tags || !Array.isArray(reference.custom.tags)) {
+    return null;
+  }
+  const normalizedQuery = normalizePreservingCase(queryValue);
+  for (const tag of reference.custom.tags) {
+    if (typeof tag === "string") {
+      const normalizedTag = normalizePreservingCase(tag);
+      if (matchWithUppercaseSensitivity(normalizedQuery, normalizedTag)) {
+        return {
+          field: "tag",
+          strength: "partial",
+          value: tag
+        };
+      }
+    }
+  }
+  return null;
+}
 const FIELD_MAP = {
   author: "author",
   title: "title",
@@ -1104,9 +1086,9 @@ function matchFieldValue(field, tokenValue, reference) {
     }
     return null;
   }
-  const normalizedFieldValue = normalize(fieldValue);
-  const normalizedQuery = normalize(tokenValue);
-  if (normalizedFieldValue.includes(normalizedQuery)) {
+  const normalizedFieldValue = normalizePreservingCase(fieldValue);
+  const normalizedQuery = normalizePreservingCase(tokenValue);
+  if (matchWithUppercaseSensitivity(normalizedQuery, normalizedFieldValue)) {
     return {
       field,
       strength: "partial",
@@ -1133,6 +1115,11 @@ function matchSpecificField(token, reference) {
     if (keywordMatch) matches.push(keywordMatch);
     return matches;
   }
+  if (fieldToSearch === "tag") {
+    const tagMatch = matchTag(token.value, reference);
+    if (tagMatch) matches.push(tagMatch);
+    return matches;
+  }
   const actualField = FIELD_MAP[fieldToSearch] || fieldToSearch;
   const match = matchFieldValue(actualField, token.value, reference);
   if (match) matches.push(match);
@@ -1158,11 +1145,14 @@ function matchSingleField(field, tokenValue, reference) {
   if (field === "keyword") {
     return matchKeyword(tokenValue, reference);
   }
+  if (field === "tag") {
+    return matchTag(tokenValue, reference);
+  }
   return matchFieldValue(field, tokenValue, reference);
 }
 function matchAllFields(token, reference) {
   const matches = [];
-  const specialFields = ["year", "URL", "keyword"];
+  const specialFields = ["year", "URL", "keyword", "tag"];
   for (const field of specialFields) {
     const match = matchSingleField(field, token.value, reference);
     if (match) matches.push(match);
@@ -1377,39 +1367,191 @@ function detectDuplicate(item, existingReferences) {
     matches
   };
 }
+const DEFAULT_DEBOUNCE_MS = 500;
+const DEFAULT_POLL_INTERVAL_MS = 5e3;
+const DEFAULT_RETRY_DELAY_MS = 200;
+const DEFAULT_MAX_RETRIES = 10;
+function shouldIgnore(filePath) {
+  const basename = path.basename(filePath);
+  if (basename.endsWith(".tmp")) return true;
+  if (basename.endsWith(".bak")) return true;
+  if (basename.includes(".conflict.")) return true;
+  if (basename.endsWith(".lock")) return true;
+  if (basename.startsWith(".") && basename.endsWith(".swp")) return true;
+  if (basename.endsWith("~")) return true;
+  return false;
+}
+class FileWatcher extends EventEmitter {
+  watchPath;
+  debounceMs;
+  pollIntervalMs;
+  usePolling;
+  retryDelayMs;
+  maxRetries;
+  watcher = null;
+  watching = false;
+  debounceTimers = /* @__PURE__ */ new Map();
+  constructor(watchPath, options) {
+    super();
+    this.watchPath = watchPath;
+    this.debounceMs = options?.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+    this.pollIntervalMs = options?.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    this.usePolling = options?.usePolling ?? false;
+    this.retryDelayMs = options?.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
+    this.maxRetries = options?.maxRetries ?? DEFAULT_MAX_RETRIES;
+  }
+  /**
+   * Start watching for file changes
+   */
+  async start() {
+    if (this.watching) {
+      return;
+    }
+    return new Promise((resolve, reject) => {
+      this.watcher = chokidar.watch(this.watchPath, {
+        ignored: shouldIgnore,
+        persistent: true,
+        usePolling: this.usePolling,
+        interval: this.pollIntervalMs,
+        ignoreInitial: true,
+        awaitWriteFinish: false
+      });
+      this.watcher.on("ready", () => {
+        this.watching = true;
+        this.emit("ready");
+        resolve();
+      });
+      this.watcher.on("error", (error) => {
+        this.emit("error", error);
+        if (!this.watching) {
+          reject(error);
+        }
+      });
+      this.watcher.on("change", (filePath) => {
+        this.handleFileChange(filePath);
+      });
+      this.watcher.on("add", (filePath) => {
+        this.handleFileChange(filePath);
+      });
+    });
+  }
+  /**
+   * Handle file change with debouncing
+   */
+  handleFileChange(filePath) {
+    const existingTimer = this.debounceTimers.get(filePath);
+    if (existingTimer) {
+      clearTimeout(existingTimer);
+    }
+    const timer = setTimeout(() => {
+      this.debounceTimers.delete(filePath);
+      this.emit("change", filePath);
+      this.tryParseJsonFile(filePath);
+    }, this.debounceMs);
+    this.debounceTimers.set(filePath, timer);
+  }
+  /**
+   * Try to parse JSON file with retries
+   */
+  async tryParseJsonFile(filePath) {
+    if (path.extname(filePath).toLowerCase() !== ".json") {
+      return;
+    }
+    let lastError = null;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        const content = await fs.readFile(filePath, "utf-8");
+        const parsed = JSON.parse(content);
+        this.emit("parsed", filePath, parsed);
+        return;
+      } catch (error) {
+        lastError = error;
+        if (attempt < this.maxRetries) {
+          await this.delay(this.retryDelayMs);
+        }
+      }
+    }
+    this.emit("parseError", filePath, lastError);
+  }
+  /**
+   * Delay helper
+   */
+  delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  /**
+   * Stop watching for file changes
+   */
+  close() {
+    if (this.watcher) {
+      this.watcher.close();
+      this.watcher = null;
+    }
+    for (const timer of this.debounceTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.debounceTimers.clear();
+    this.watching = false;
+  }
+  /**
+   * Get the watched path
+   */
+  getPath() {
+    return this.watchPath;
+  }
+  /**
+   * Check if the watcher is currently active
+   */
+  isWatching() {
+    return this.watching;
+  }
+  /**
+   * Get the debounce time in milliseconds
+   */
+  getDebounceMs() {
+    return this.debounceMs;
+  }
+  /**
+   * Get the poll interval in milliseconds
+   */
+  getPollIntervalMs() {
+    return this.pollIntervalMs;
+  }
+  /**
+   * Get the retry delay in milliseconds
+   */
+  getRetryDelayMs() {
+    return this.retryDelayMs;
+  }
+  /**
+   * Get the maximum number of retries
+   */
+  getMaxRetries() {
+    return this.maxRetries;
+  }
+}
 export {
-  generateUuid as A,
-  isValidUuid as B,
   CslLibrarySchema as C,
-  ensureCustomMetadata as D,
-  extractUuidFromCustom as E,
+  FileWatcher as F,
   Library as L,
   Reference as R,
   computeHash as a,
-  backupConfigSchema as b,
+  sortResults as b,
   computeFileHash as c,
-  configSchema as d,
-  defaultConfig as e,
-  getDefaultCurrentDirConfigFilename as f,
-  getDefaultBackupDirectory as g,
-  getDefaultLibraryPath as h,
-  getDefaultUserConfigPath as i,
-  logLevelSchema as j,
-  normalize as k,
-  loadConfig as l,
-  sortResults as m,
-  normalizePartialConfig as n,
-  detectDuplicate as o,
-  partialConfigSchema as p,
-  CslItemSchema as q,
-  parseCslJson as r,
+  detectDuplicate as d,
+  CslItemSchema as e,
+  serializeCslJson as f,
+  generateId as g,
+  generateIdWithCollisionCheck as h,
+  normalizeText as i,
+  generateUuid as j,
+  isValidUuid as k,
+  ensureCustomMetadata as l,
+  extractUuidFromCustom as m,
+  normalize as n,
+  parseCslJson as p,
   search as s,
   tokenize as t,
-  serializeCslJson as u,
-  writeCslJson as v,
-  watchConfigSchema as w,
-  generateId as x,
-  generateIdWithCollisionCheck as y,
-  normalizeText as z
+  writeCslJson as w
 };
-//# sourceMappingURL=detector-BF8Mcc72.js.map
+//# sourceMappingURL=file-watcher-B-SiUw5f.js.map