@ncukondo/reference-manager 0.1.0 → 0.3.0

package/README.md

@@ -7,6 +7,7 @@ A local reference management tool using CSL-JSON as the single source of truth.
 - **CSL-JSON Native**: Uses CSL-JSON format as the primary data model
 - **Command-line Interface**: Comprehensive CLI with search, add, update, remove commands
 - **HTTP Server**: Optional background server for improved performance
+- **Fulltext Management**: Attach PDF and Markdown files to references
 - **Duplicate Detection**: Automatic detection via DOI, PMID, or title+author+year
 - **Smart Search**: Full-text search with field-specific queries
 - **File Monitoring**: Automatic reload on external changes
@@ -66,6 +67,39 @@ ref server status
 ref server stop
 ```
 
+### Fulltext Management
+
+Attach PDF and Markdown files to references for full-text storage.
+
+```bash
+# Attach a PDF to a reference
+ref fulltext attach smith-2020 ~/papers/smith-2020.pdf
+
+# Attach a Markdown notes file
+ref fulltext attach smith-2020 ~/notes/smith-2020.md
+
+# Attach with explicit type (when extension doesn't match)
+ref fulltext attach smith-2020 --pdf ~/downloads/paper.txt
+
+# Move file instead of copy
+ref fulltext attach smith-2020 ~/papers/smith-2020.pdf --move
+
+# Overwrite existing attachment
+ref fulltext attach smith-2020 ~/papers/smith-2020-revised.pdf --force
+
+# Get attached file path
+ref fulltext get smith-2020 --pdf
+
+# Output file content to stdout
+ref fulltext get smith-2020 --pdf --stdout
+
+# Detach file (keeps file on disk)
+ref fulltext detach smith-2020 --pdf
+
+# Detach and delete file
+ref fulltext detach smith-2020 --pdf --delete
+```
+
 ### Output Formats
 
 ```bash
@@ -98,8 +132,14 @@ max_age_days = 30
 [server]
 auto_start = true
 auto_stop_minutes = 60
+
+[fulltext]
+directory = "~/references/fulltext"
 ```
 
+Environment variables:
+- `REFERENCE_MANAGER_FULLTEXT_DIR`: Override fulltext directory
+
 See `spec/architecture/cli.md` for full configuration options.
 
 ## Development

package/dist/chunks/detector-DHztTaFY.js

@@ -0,0 +1,619 @@
+import { z } from "zod";
+const CslNameSchema = z.object({
+  family: z.string().optional(),
+  given: z.string().optional(),
+  literal: z.string().optional(),
+  "dropping-particle": z.string().optional(),
+  "non-dropping-particle": z.string().optional(),
+  suffix: z.string().optional()
+});
+const CslDateSchema = z.object({
+  "date-parts": z.array(z.array(z.number())).optional(),
+  raw: z.string().optional(),
+  season: z.string().optional(),
+  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(),
+  fulltext: CslFulltextSchema.optional()
+}).passthrough();
+const CslItemSchema = z.object({
+  id: z.string(),
+  type: z.string(),
+  title: z.string().optional(),
+  author: z.array(CslNameSchema).optional(),
+  editor: z.array(CslNameSchema).optional(),
+  issued: CslDateSchema.optional(),
+  accessed: CslDateSchema.optional(),
+  "container-title": z.string().optional(),
+  volume: z.string().optional(),
+  issue: z.string().optional(),
+  page: z.string().optional(),
+  DOI: z.string().optional(),
+  PMID: z.string().optional(),
+  PMCID: z.string().optional(),
+  ISBN: z.string().optional(),
+  ISSN: z.string().optional(),
+  URL: z.string().optional(),
+  abstract: z.string().optional(),
+  publisher: z.string().optional(),
+  "publisher-place": z.string().optional(),
+  note: z.string().optional(),
+  keyword: z.array(z.string()).optional(),
+  custom: CslCustomSchema.optional()
+  // Allow additional fields
+}).passthrough();
+const CslLibrarySchema = z.array(CslItemSchema);
+const VALID_FIELDS = /* @__PURE__ */ new Set([
+  "author",
+  "title",
+  "year",
+  "doi",
+  "pmid",
+  "pmcid",
+  "url",
+  "keyword"
+]);
+function isWhitespace(query, index) {
+  return /\s/.test(query.charAt(index));
+}
+function isQuote(query, index) {
+  return query.charAt(index) === '"';
+}
+function tokenize(query) {
+  const tokens = [];
+  let i = 0;
+  while (i < query.length) {
+    if (isWhitespace(query, i)) {
+      i++;
+      continue;
+    }
+    const result = parseNextToken(query, i);
+    if (result.token) {
+      tokens.push(result.token);
+    }
+    i = result.nextIndex;
+  }
+  return {
+    original: query,
+    tokens
+  };
+}
+function hasWhitespaceBetween(query, start, end) {
+  for (let j = start; j < end; j++) {
+    if (isWhitespace(query, j)) {
+      return true;
+    }
+  }
+  return false;
+}
+function tryParseFieldValue(query, startIndex) {
+  const colonIndex = query.indexOf(":", startIndex);
+  if (colonIndex === -1) {
+    return null;
+  }
+  if (hasWhitespaceBetween(query, startIndex, colonIndex)) {
+    return null;
+  }
+  const fieldName = query.substring(startIndex, colonIndex);
+  if (!VALID_FIELDS.has(fieldName)) {
+    return null;
+  }
+  const afterColon = colonIndex + 1;
+  if (afterColon >= query.length || isWhitespace(query, afterColon)) {
+    return { token: null, nextIndex: afterColon };
+  }
+  if (isQuote(query, afterColon)) {
+    const quoteResult = parseQuotedValue(query, afterColon);
+    if (quoteResult.value !== null) {
+      return {
+        token: {
+          raw: query.substring(startIndex, quoteResult.nextIndex),
+          value: quoteResult.value,
+          field: fieldName,
+          isPhrase: true
+        },
+        nextIndex: quoteResult.nextIndex
+      };
+    }
+    return null;
+  }
+  const valueResult = parseUnquotedValue(query, afterColon);
+  return {
+    token: {
+      raw: query.substring(startIndex, valueResult.nextIndex),
+      value: valueResult.value,
+      field: fieldName,
+      isPhrase: false
+    },
+    nextIndex: valueResult.nextIndex
+  };
+}
+function parseQuotedToken(query, startIndex) {
+  const quoteResult = parseQuotedValue(query, startIndex);
+  if (quoteResult.value !== null) {
+    return {
+      token: {
+        raw: query.substring(startIndex, quoteResult.nextIndex),
+        value: quoteResult.value,
+        isPhrase: true
+      },
+      nextIndex: quoteResult.nextIndex
+    };
+  }
+  if (quoteResult.nextIndex > startIndex) {
+    return { token: null, nextIndex: quoteResult.nextIndex };
+  }
+  const valueResult = parseUnquotedValue(query, startIndex, true);
+  return {
+    token: {
+      raw: valueResult.value,
+      value: valueResult.value,
+      isPhrase: false
+    },
+    nextIndex: valueResult.nextIndex
+  };
+}
+function parseRegularToken(query, startIndex) {
+  const valueResult = parseUnquotedValue(query, startIndex);
+  return {
+    token: {
+      raw: valueResult.value,
+      value: valueResult.value,
+      isPhrase: false
+    },
+    nextIndex: valueResult.nextIndex
+  };
+}
+function parseNextToken(query, startIndex) {
+  const fieldResult = tryParseFieldValue(query, startIndex);
+  if (fieldResult !== null) {
+    return fieldResult;
+  }
+  if (isQuote(query, startIndex)) {
+    return parseQuotedToken(query, startIndex);
+  }
+  return parseRegularToken(query, startIndex);
+}
+function parseQuotedValue(query, startIndex) {
+  if (!isQuote(query, startIndex)) {
+    return { value: null, nextIndex: startIndex };
+  }
+  let i = startIndex + 1;
+  const valueStart = i;
+  while (i < query.length && !isQuote(query, i)) {
+    i++;
+  }
+  if (i >= query.length) {
+    return { value: null, nextIndex: startIndex };
+  }
+  const value = query.substring(valueStart, i);
+  i++;
+  if (value.trim() === "") {
+    return { value: null, nextIndex: i };
+  }
+  return { value, nextIndex: i };
+}
+function parseUnquotedValue(query, startIndex, includeQuotes = false) {
+  let i = startIndex;
+  while (i < query.length && !isWhitespace(query, i)) {
+    if (!includeQuotes && isQuote(query, i)) {
+      break;
+    }
+    i++;
+  }
+  return {
+    value: query.substring(startIndex, i),
+    nextIndex: i
+  };
+}
+function normalize(text) {
+  let normalized = text.normalize("NFKC");
+  normalized = normalized.toLowerCase();
+  normalized = normalized.normalize("NFD").replace(new RegExp("\\p{M}", "gu"), "");
+  normalized = normalized.replace(/[^\p{L}\p{N}/\s]/gu, " ");
+  normalized = normalized.replace(/\s+/g, " ").trim();
+  return normalized;
+}
+const ID_FIELDS = /* @__PURE__ */ new Set(["DOI", "PMID", "PMCID", "URL"]);
+function extractYear$2(reference) {
+  if (reference.issued?.["date-parts"]?.[0]?.[0]) {
+    return String(reference.issued["date-parts"][0][0]);
+  }
+  return "0000";
+}
+function extractAuthors(reference) {
+  if (!reference.author || reference.author.length === 0) {
+    return "";
+  }
+  return reference.author.map((author) => {
+    const family = author.family || "";
+    const givenInitial = author.given ? author.given[0] : "";
+    return givenInitial ? `${family} ${givenInitial}` : family;
+  }).join(" ");
+}
+function getFieldValue(reference, field) {
+  if (field === "year") {
+    return extractYear$2(reference);
+  }
+  if (field === "author") {
+    return extractAuthors(reference);
+  }
+  const value = reference[field];
+  if (typeof value === "string") {
+    return value;
+  }
+  if (field.startsWith("custom.")) {
+    const customField = field.substring(7);
+    const customValue = reference.custom?.[customField];
+    if (typeof customValue === "string") {
+      return customValue;
+    }
+  }
+  return null;
+}
+function matchUrl(queryValue, reference) {
+  if (reference.URL === queryValue) {
+    return {
+      field: "URL",
+      strength: "exact",
+      value: reference.URL
+    };
+  }
+  const additionalUrls = reference.custom?.additional_urls;
+  if (Array.isArray(additionalUrls)) {
+    for (const url of additionalUrls) {
+      if (typeof url === "string" && url === queryValue) {
+        return {
+          field: "custom.additional_urls",
+          strength: "exact",
+          value: url
+        };
+      }
+    }
+  }
+  return null;
+}
+function matchKeyword(queryValue, reference) {
+  if (!reference.keyword || !Array.isArray(reference.keyword)) {
+    return null;
+  }
+  const normalizedQuery = normalize(queryValue);
+  for (const keyword of reference.keyword) {
+    if (typeof keyword === "string") {
+      const normalizedKeyword = normalize(keyword);
+      if (normalizedKeyword.includes(normalizedQuery)) {
+        return {
+          field: "keyword",
+          strength: "partial",
+          value: keyword
+        };
+      }
+    }
+  }
+  return null;
+}
+const FIELD_MAP = {
+  author: "author",
+  title: "title",
+  doi: "DOI",
+  pmid: "PMID",
+  pmcid: "PMCID"
+};
+function matchYearField(tokenValue, reference) {
+  const year = extractYear$2(reference);
+  if (year === tokenValue) {
+    return {
+      field: "year",
+      strength: "exact",
+      value: year
+    };
+  }
+  return null;
+}
+function matchFieldValue(field, tokenValue, reference) {
+  const fieldValue = getFieldValue(reference, field);
+  if (fieldValue === null) {
+    return null;
+  }
+  if (ID_FIELDS.has(field)) {
+    if (fieldValue === tokenValue) {
+      return {
+        field,
+        strength: "exact",
+        value: fieldValue
+      };
+    }
+    return null;
+  }
+  const normalizedFieldValue = normalize(fieldValue);
+  const normalizedQuery = normalize(tokenValue);
+  if (normalizedFieldValue.includes(normalizedQuery)) {
+    return {
+      field,
+      strength: "partial",
+      value: fieldValue
+    };
+  }
+  return null;
+}
+function matchSpecificField(token, reference) {
+  const matches = [];
+  const fieldToSearch = token.field;
+  if (fieldToSearch === "url") {
+    const urlMatch = matchUrl(token.value, reference);
+    if (urlMatch) matches.push(urlMatch);
+    return matches;
+  }
+  if (fieldToSearch === "year") {
+    const yearMatch = matchYearField(token.value, reference);
+    if (yearMatch) matches.push(yearMatch);
+    return matches;
+  }
+  if (fieldToSearch === "keyword") {
+    const keywordMatch = matchKeyword(token.value, reference);
+    if (keywordMatch) matches.push(keywordMatch);
+    return matches;
+  }
+  const actualField = FIELD_MAP[fieldToSearch] || fieldToSearch;
+  const match = matchFieldValue(actualField, token.value, reference);
+  if (match) matches.push(match);
+  return matches;
+}
+const STANDARD_SEARCH_FIELDS = [
+  "title",
+  "author",
+  "container-title",
+  "publisher",
+  "DOI",
+  "PMID",
+  "PMCID",
+  "abstract"
+];
+function matchSingleField(field, tokenValue, reference) {
+  if (field === "year") {
+    return matchYearField(tokenValue, reference);
+  }
+  if (field === "URL") {
+    return matchUrl(tokenValue, reference);
+  }
+  if (field === "keyword") {
+    return matchKeyword(tokenValue, reference);
+  }
+  return matchFieldValue(field, tokenValue, reference);
+}
+function matchAllFields(token, reference) {
+  const matches = [];
+  const specialFields = ["year", "URL", "keyword"];
+  for (const field of specialFields) {
+    const match = matchSingleField(field, token.value, reference);
+    if (match) matches.push(match);
+  }
+  for (const field of STANDARD_SEARCH_FIELDS) {
+    const match = matchFieldValue(field, token.value, reference);
+    if (match) matches.push(match);
+  }
+  return matches;
+}
+function matchToken(token, reference) {
+  if (token.field) {
+    return matchSpecificField(token, reference);
+  }
+  return matchAllFields(token, reference);
+}
+function matchReference(reference, tokens) {
+  if (tokens.length === 0) {
+    return null;
+  }
+  const tokenMatches = [];
+  let overallStrength = "none";
+  for (const token of tokens) {
+    const matches = matchToken(token, reference);
+    if (matches.length === 0) {
+      return null;
+    }
+    const tokenStrength = matches.some((m) => m.strength === "exact") ? "exact" : "partial";
+    if (tokenStrength === "exact") {
+      overallStrength = "exact";
+    } else if (tokenStrength === "partial" && overallStrength === "none") {
+      overallStrength = "partial";
+    }
+    tokenMatches.push({
+      token,
+      matches
+    });
+  }
+  const score = overallStrength === "exact" ? 100 + tokenMatches.length : 50 + tokenMatches.length;
+  return {
+    reference,
+    tokenMatches,
+    overallStrength,
+    score
+  };
+}
+function search(references, tokens) {
+  const results = [];
+  for (const reference of references) {
+    const match = matchReference(reference, tokens);
+    if (match) {
+      results.push(match);
+    }
+  }
+  return results;
+}
+function extractYear$1(reference) {
+  if (reference.issued?.["date-parts"]?.[0]?.[0]) {
+    return String(reference.issued["date-parts"][0][0]);
+  }
+  return "0000";
+}
+function extractFirstAuthorFamily(reference) {
+  if (!reference.author || reference.author.length === 0) {
+    return "";
+  }
+  return reference.author[0]?.family || "";
+}
+function extractTitle(reference) {
+  return reference.title || "";
+}
+function compareStrength(a, b) {
+  const strengthOrder = { exact: 2, partial: 1, none: 0 };
+  return strengthOrder[b] - strengthOrder[a];
+}
+function compareYear(a, b) {
+  const yearA = extractYear$1(a);
+  const yearB = extractYear$1(b);
+  return Number(yearB) - Number(yearA);
+}
+function compareAuthor(a, b) {
+  const authorA = extractFirstAuthorFamily(a).toLowerCase();
+  const authorB = extractFirstAuthorFamily(b).toLowerCase();
+  if (authorA === "" && authorB !== "") return 1;
+  if (authorA !== "" && authorB === "") return -1;
+  return authorA.localeCompare(authorB);
+}
+function compareTitle(a, b) {
+  const titleA = extractTitle(a).toLowerCase();
+  const titleB = extractTitle(b).toLowerCase();
+  if (titleA === "" && titleB !== "") return 1;
+  if (titleA !== "" && titleB === "") return -1;
+  return titleA.localeCompare(titleB);
+}
+function sortResults(results) {
+  const indexed = results.map((result, index) => ({ result, index }));
+  const sorted = indexed.sort((a, b) => {
+    const strengthDiff = compareStrength(a.result.overallStrength, b.result.overallStrength);
+    if (strengthDiff !== 0) return strengthDiff;
+    const yearDiff = compareYear(a.result.reference, b.result.reference);
+    if (yearDiff !== 0) return yearDiff;
+    const authorDiff = compareAuthor(a.result.reference, b.result.reference);
+    if (authorDiff !== 0) return authorDiff;
+    const titleDiff = compareTitle(a.result.reference, b.result.reference);
+    if (titleDiff !== 0) return titleDiff;
+    return a.index - b.index;
+  });
+  return sorted.map((item) => item.result);
+}
+function normalizeDoi(doi) {
+  const normalized = doi.replace(/^https?:\/\/doi\.org\//i, "").replace(/^https?:\/\/dx\.doi\.org\//i, "").replace(/^doi:/i, "");
+  return normalized;
+}
+function extractYear(item) {
+  const dateParts = item.issued?.["date-parts"]?.[0];
+  if (!dateParts || dateParts.length === 0) {
+    return null;
+  }
+  return String(dateParts[0]);
+}
+function normalizeAuthors(item) {
+  if (!item.author || item.author.length === 0) {
+    return null;
+  }
+  const authorStrings = item.author.map((author) => {
+    const family = author.family || "";
+    const givenInitial = author.given ? author.given.charAt(0) : "";
+    return `${family} ${givenInitial}`.trim();
+  });
+  return normalize(authorStrings.join(" "));
+}
+function checkDoiMatch(item, existing) {
+  if (!item.DOI || !existing.DOI) {
+    return null;
+  }
+  const normalizedItemDoi = normalizeDoi(item.DOI);
+  const normalizedExistingDoi = normalizeDoi(existing.DOI);
+  if (normalizedItemDoi === normalizedExistingDoi) {
+    return {
+      type: "doi",
+      existing,
+      details: {
+        doi: normalizedExistingDoi
+      }
+    };
+  }
+  return null;
+}
+function checkPmidMatch(item, existing) {
+  if (!item.PMID || !existing.PMID) {
+    return null;
+  }
+  if (item.PMID === existing.PMID) {
+    return {
+      type: "pmid",
+      existing,
+      details: {
+        pmid: existing.PMID
+      }
+    };
+  }
+  return null;
+}
+function checkTitleAuthorYearMatch(item, existing) {
+  const itemTitle = item.title ? normalize(item.title) : null;
+  const existingTitle = existing.title ? normalize(existing.title) : null;
+  const itemAuthors = normalizeAuthors(item);
+  const existingAuthors = normalizeAuthors(existing);
+  const itemYear = extractYear(item);
+  const existingYear = extractYear(existing);
+  if (!itemTitle || !existingTitle || !itemAuthors || !existingAuthors || !itemYear || !existingYear) {
+    return null;
+  }
+  if (itemTitle === existingTitle && itemAuthors === existingAuthors && itemYear === existingYear) {
+    return {
+      type: "title-author-year",
+      existing,
+      details: {
+        normalizedTitle: existingTitle,
+        normalizedAuthors: existingAuthors,
+        year: existingYear
+      }
+    };
+  }
+  return null;
+}
+function checkSingleDuplicate(item, existing) {
+  const doiMatch = checkDoiMatch(item, existing);
+  if (doiMatch) {
+    return doiMatch;
+  }
+  const pmidMatch = checkPmidMatch(item, existing);
+  if (pmidMatch) {
+    return pmidMatch;
+  }
+  return checkTitleAuthorYearMatch(item, existing);
+}
+function detectDuplicate(item, existingReferences) {
+  const matches = [];
+  const itemUuid = item.custom?.uuid;
+  for (const existing of existingReferences) {
+    if (itemUuid && existing.custom?.uuid === itemUuid) {
+      continue;
+    }
+    const match = checkSingleDuplicate(item, existing);
+    if (match) {
+      matches.push(match);
+    }
+  }
+  return {
+    isDuplicate: matches.length > 0,
+    matches
+  };
+}
+export {
+  CslLibrarySchema as C,
+  sortResults as a,
+  CslItemSchema as b,
+  detectDuplicate as d,
+  normalize as n,
+  search as s,
+  tokenize as t
+};
+//# sourceMappingURL=detector-DHztTaFY.js.map