@ncukondo/reference-manager 0.1.0 → 0.3.0

package/dist/cli.js

@@ -1,11 +1,21 @@
 import { Command } from "commander";
 import { z } from "zod";
-import { o as detectDuplicate, R as Reference, t as tokenize, s as search$1, m as sortResults, l as loadConfig, L as Library } from "./chunks/detector-BF8Mcc72.js";
-import { promises, readFileSync } from "node:fs";
+import { l as loadConfig, L as Library } from "./chunks/loader-mQ25o6cV.js";
+import { promises, existsSync, mkdtempSync, writeFileSync, readFileSync } from "node:fs";
 import * as os from "node:os";
+import { tmpdir } from "node:os";
 import * as path from "node:path";
-import { stdin, stdout } from "node:process";
+import { join, extname } from "node:path";
+import { a as addReferences, c as citeReferences, u as updateReference, l as listReferences, r as removeReference, s as searchReferences } from "./chunks/search-Be9vzUIH.js";
+import { mkdir, unlink, rename, copyFile, rm, readFile } from "node:fs/promises";
 import { spawn } from "node:child_process";
+import { stdin, stdout } from "node:process";
+const version = "0.3.0";
+const description = "A local reference management tool using CSL-JSON as the single source of truth";
+const packageJson = {
+  version,
+  description
+};
 function getPortfilePath() {
   const tmpDir = os.tmpdir();
   return path.join(tmpDir, "reference-manager", "server.port");
@@ -67,192 +77,620 @@ function isProcessRunning(pid) {
     return false;
   }
 }
-function 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;
-}
-function resolveIdCollision(baseId, existing) {
-  const existingIds = new Set(existing.map((item) => item.id));
-  if (!existingIds.has(baseId)) {
-    return { id: baseId, changed: false };
-  }
-  let index = 0;
-  let newId;
-  do {
-    const suffix = generateSuffix(index);
-    newId = `${baseId}${suffix}`;
-    index++;
-  } while (existingIds.has(newId));
-  return { id: newId, changed: true };
-}
-async function add(existing, newItem, options) {
-  if (!options.force) {
-    const duplicateResult = detectDuplicate(newItem, existing);
-    if (duplicateResult.matches.length > 0) {
-      return {
-        added: false,
-        item: newItem,
-        idChanged: false,
-        duplicate: duplicateResult.matches[0]
-      };
+const MAX_ERROR_LENGTH = 80;
+async function executeAdd(options, context) {
+  const { inputs, force, format, pubmedConfig, stdinContent } = options;
+  if (context.type === "server") {
+    const serverOptions = { force };
+    if (format !== void 0) {
+      serverOptions.format = format;
+    }
+    if (stdinContent !== void 0) {
+      serverOptions.stdinContent = stdinContent;
     }
+    return context.client.addFromInputs(inputs, serverOptions);
   }
-  const originalId = newItem.id;
-  const { id, changed } = resolveIdCollision(originalId, existing);
-  const finalItem = {
-    ...newItem,
-    id
-  };
+  const addOptions = { force };
+  if (format !== void 0) {
+    addOptions.format = format;
+  }
+  if (pubmedConfig !== void 0) {
+    addOptions.pubmedConfig = pubmedConfig;
+  }
+  if (stdinContent !== void 0) {
+    addOptions.stdinContent = stdinContent;
+  }
+  return addReferences(inputs, context.library, addOptions);
+}
+function formatAddedItem(item) {
+  const idPart = item.idChanged ? `${item.id} (was: ${item.originalId})` : item.id;
+  const title = item.title ?? "(no title)";
+  return `  - ${idPart}: "${title}"`;
+}
+function formatFailedItem(item, verbose) {
+  let error = item.error;
+  if (!verbose && error.length > MAX_ERROR_LENGTH) {
+    error = `${error.substring(0, MAX_ERROR_LENGTH - 3)}...`;
+  }
+  if (!verbose && error.includes("\n")) {
+    error = error.split("\n")[0] ?? error;
+  }
+  return `  - ${item.source}: ${error}`;
+}
+function formatSkippedItem(item) {
+  return `  - ${item.source}: matches existing '${item.existingId}'`;
+}
+function formatAddOutput(result, verbose) {
+  const lines = [];
+  if (result.added.length > 0) {
+    lines.push(`Added ${result.added.length} reference(s):`);
+    for (const item of result.added) {
+      lines.push(formatAddedItem(item));
+    }
+  } else if (result.failed.length === 0 && result.skipped.length === 0) {
+    lines.push("Added 0 reference(s).");
+  }
+  if (result.failed.length > 0) {
+    if (lines.length > 0) lines.push("");
+    lines.push(`Failed to add ${result.failed.length} item(s):`);
+    for (const item of result.failed) {
+      lines.push(formatFailedItem(item, verbose));
+    }
+  }
+  if (result.skipped.length > 0) {
+    if (lines.length > 0) lines.push("");
+    lines.push(`Skipped ${result.skipped.length} duplicate(s):`);
+    for (const item of result.skipped) {
+      lines.push(formatSkippedItem(item));
+    }
+  }
+  return lines.join("\n");
+}
+function getExitCode(result) {
+  if (result.added.length > 0) {
+    return 0;
+  }
+  if (result.failed.length > 0) {
+    return 1;
+  }
+  return 0;
+}
+async function validateOptions$2(options) {
+  if (options.format && !["text", "html", "rtf"].includes(options.format)) {
+    throw new Error(`Invalid format '${options.format}'. Must be one of: text, html, rtf`);
+  }
+  if (options.cslFile) {
+    const fs = await import("node:fs");
+    if (!fs.existsSync(options.cslFile)) {
+      throw new Error(`CSL file '${options.cslFile}' not found`);
+    }
+  }
+}
+function buildServerCiteOptions(options) {
   return {
-    added: true,
-    item: finalItem,
-    idChanged: changed,
-    originalId: changed ? originalId : void 0
+    identifiers: options.identifiers,
+    ...options.uuid !== void 0 && { byUuid: options.uuid },
+    ...options.inText !== void 0 && { inText: options.inText },
+    ...options.style !== void 0 && { style: options.style },
+    ...options.cslFile !== void 0 && { cslFile: options.cslFile },
+    ...options.locale !== void 0 && { locale: options.locale },
+    ...options.format !== void 0 && {
+      format: options.format === "rtf" ? "text" : options.format
+    }
   };
 }
-function mapEntryType(cslType) {
-  const typeMap = {
-    article: "article",
-    "article-journal": "article",
-    "article-magazine": "article",
-    "article-newspaper": "article",
-    book: "book",
-    chapter: "inbook",
-    "paper-conference": "inproceedings",
-    thesis: "phdthesis",
-    report: "techreport",
-    webpage: "misc"
+function buildOperationCiteOptions(options) {
+  return {
+    identifiers: options.identifiers,
+    ...options.uuid !== void 0 && { byUuid: options.uuid },
+    ...options.style !== void 0 && { style: options.style },
+    ...options.cslFile !== void 0 && { cslFile: options.cslFile },
+    ...options.locale !== void 0 && { locale: options.locale },
+    ...options.format !== void 0 && { format: options.format },
+    ...options.inText !== void 0 && { inText: options.inText }
   };
-  return typeMap[cslType] || "misc";
 }
-function formatBibtexAuthor(author) {
-  if (author.literal) {
-    return author.literal;
+async function executeCite(options, context) {
+  await validateOptions$2(options);
+  if (context.type === "server") {
+    return context.client.cite(buildServerCiteOptions(options));
   }
-  const family = author.family || "";
-  const given = author.given || "";
-  return given ? `${family}, ${given}` : family;
+  return citeReferences(context.library, buildOperationCiteOptions(options));
 }
-function formatBibtexAuthors(authors) {
-  return authors.map(formatBibtexAuthor).join(" and ");
+function formatCiteOutput(result) {
+  const lines = [];
+  for (const r of result.results) {
+    if (r.success) {
+      lines.push(r.citation);
+    }
+  }
+  return lines.join("\n");
+}
+function formatCiteErrors(result) {
+  const lines = [];
+  for (const r of result.results) {
+    if (!r.success) {
+      lines.push(`Error for '${r.identifier}': ${r.error}`);
+    }
+  }
+  return lines.join("\n");
 }
-function formatField(name, value) {
-  return `  ${name} = {${value}},`;
+function getCiteExitCode(result) {
+  const hasSuccess = result.results.some((r) => r.success);
+  const hasError = result.results.some((r) => !r.success);
+  if (hasSuccess) {
+    return 0;
+  }
+  if (hasError) {
+    return 1;
+  }
+  return 0;
 }
-function addBasicFields(lines, item) {
-  if (item.title) {
-    lines.push(formatField("title", item.title));
+const FULLTEXT_EXTENSIONS = {
+  pdf: ".pdf",
+  markdown: ".md"
+};
+function generateFulltextFilename(item, type) {
+  const uuid = item.custom?.uuid;
+  if (!uuid) {
+    throw new Error("Missing uuid in custom field");
   }
-  if (item.author && item.author.length > 0) {
-    lines.push(formatField("author", formatBibtexAuthors(item.author)));
+  const parts = [item.id];
+  if (item.PMID && item.PMID.length > 0) {
+    parts.push(`PMID${item.PMID}`);
   }
-  const year = item.issued?.["date-parts"]?.[0]?.[0];
-  if (year) {
-    lines.push(formatField("year", String(year)));
+  parts.push(uuid);
+  return parts.join("-") + FULLTEXT_EXTENSIONS[type];
+}
+class FulltextIOError extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "FulltextIOError";
+  }
+}
+class FulltextNotAttachedError extends Error {
+  constructor(itemId, type) {
+    super(`No ${type} attached to reference ${itemId}`);
+    this.itemId = itemId;
+    this.type = type;
+    this.name = "FulltextNotAttachedError";
   }
 }
-function addPublicationDetails(lines, item, entryType) {
-  if (item["container-title"]) {
-    if (entryType === "article") {
-      lines.push(formatField("journal", item["container-title"]));
-    } else if (entryType === "inbook" || entryType === "inproceedings") {
-      lines.push(formatField("booktitle", item["container-title"]));
+class FulltextManager {
+  constructor(fulltextDirectory) {
+    this.fulltextDirectory = fulltextDirectory;
+  }
+  /**
+   * Ensure the fulltext directory exists
+   */
+  async ensureDirectory() {
+    await mkdir(this.fulltextDirectory, { recursive: true });
+  }
+  /**
+   * Attach a file to a reference
+   */
+  async attachFile(item, sourcePath, type, options) {
+    const { move = false, force = false } = options ?? {};
+    const newFilename = generateFulltextFilename(item, type);
+    this.validateSourceFile(sourcePath);
+    const existingFilename = this.getExistingFilename(item, type);
+    if (existingFilename && !force) {
+      return {
+        filename: newFilename,
+        existingFile: existingFilename,
+        overwritten: false
+      };
+    }
+    await this.ensureDirectory();
+    const deletedOldFile = await this.deleteOldFileIfNeeded(existingFilename, newFilename, force);
+    const destPath = join(this.fulltextDirectory, newFilename);
+    await this.copyOrMoveFile(sourcePath, destPath, move);
+    const result = {
+      filename: newFilename,
+      overwritten: existingFilename !== void 0
+    };
+    if (deletedOldFile) {
+      result.deletedOldFile = deletedOldFile;
+    }
+    return result;
+  }
+  /**
+   * Validate that source file exists
+   */
+  validateSourceFile(sourcePath) {
+    if (!existsSync(sourcePath)) {
+      throw new FulltextIOError(`Source file not found: ${sourcePath}`);
+    }
+  }
+  /**
+   * Delete old file if force mode and filename changed
+   * @returns Deleted filename or undefined
+   */
+  async deleteOldFileIfNeeded(existingFilename, newFilename, force) {
+    if (!force || !existingFilename || existingFilename === newFilename) {
+      return void 0;
+    }
+    const oldPath = join(this.fulltextDirectory, existingFilename);
+    try {
+      await unlink(oldPath);
+    } catch {
+    }
+    return existingFilename;
+  }
+  /**
+   * Copy or move file to destination
+   */
+  async copyOrMoveFile(sourcePath, destPath, move) {
+    try {
+      if (move) {
+        await rename(sourcePath, destPath);
+      } else {
+        await copyFile(sourcePath, destPath);
+      }
+    } catch (error) {
+      const operation = move ? "move" : "copy";
+      throw new FulltextIOError(
+        `Failed to ${operation} file to ${destPath}`,
+        error instanceof Error ? error : void 0
+      );
+    }
+  }
+  /**
+   * Get the full path for an attached file
+   * @returns Full path or null if not attached
+   */
+  getFilePath(item, type) {
+    const filename = this.getExistingFilename(item, type);
+    if (!filename) {
+      return null;
+    }
+    return join(this.fulltextDirectory, filename);
+  }
+  /**
+   * Detach a file from a reference
+   */
+  async detachFile(item, type, options) {
+    const { delete: deleteFile = false } = options ?? {};
+    const filename = this.getExistingFilename(item, type);
+    if (!filename) {
+      throw new FulltextNotAttachedError(item.id, type);
+    }
+    if (deleteFile) {
+      const filePath = join(this.fulltextDirectory, filename);
+      try {
+        await unlink(filePath);
+      } catch {
+      }
+    }
+    return {
+      filename,
+      deleted: deleteFile
+    };
+  }
+  /**
+   * Get list of attached fulltext types
+   */
+  getAttachedTypes(item) {
+    const types = [];
+    const fulltext = item.custom?.fulltext;
+    if (fulltext?.pdf) {
+      types.push("pdf");
+    }
+    if (fulltext?.markdown) {
+      types.push("markdown");
+    }
+    return types;
+  }
+  /**
+   * Check if item has attachment
+   * @param type Optional type to check; if omitted, checks for any attachment
+   */
+  hasAttachment(item, type) {
+    if (type) {
+      return this.getExistingFilename(item, type) !== void 0;
     }
+    return this.getAttachedTypes(item).length > 0;
   }
-  if (item.volume) {
-    lines.push(formatField("volume", item.volume));
+  /**
+   * Get existing filename from item metadata
+   */
+  getExistingFilename(item, type) {
+    const fulltext = item.custom?.fulltext;
+    if (!fulltext) {
+      return void 0;
+    }
+    return fulltext[type];
   }
-  if (item.issue) {
-    lines.push(formatField("number", item.issue));
+}
+function detectType(filePath) {
+  const ext = extname(filePath).toLowerCase();
+  if (ext === ".pdf") return "pdf";
+  if (ext === ".md" || ext === ".markdown") return "markdown";
+  return void 0;
+}
+async function findReference(identifier, context, byUuid) {
+  if (context.type === "server") {
+    return context.client.find(identifier, { byUuid });
+  }
+  const ref = byUuid ? context.library.findByUuid(identifier) : context.library.findById(identifier);
+  return ref?.getItem() ?? null;
+}
+async function updateFulltextMetadata(identifier, fulltext, context, byUuid) {
+  const updates = {
+    custom: { fulltext }
+  };
+  if (context.type === "server") {
+    await context.client.update(identifier, updates, { byUuid });
+  } else {
+    await updateReference(context.library, {
+      identifier,
+      updates,
+      byUuid
+    });
   }
-  if (item.page) {
-    lines.push(formatField("pages", item.page));
+}
+async function cleanupTempDir(tempDir) {
+  if (tempDir) {
+    await rm(tempDir, { recursive: true, force: true }).catch(() => {
+    });
   }
-  if (item.publisher) {
-    lines.push(formatField("publisher", item.publisher));
+}
+function prepareStdinSource(stdinContent, fileType) {
+  try {
+    const tempDir = mkdtempSync(join(tmpdir(), "refmgr-"));
+    const ext = fileType === "pdf" ? ".pdf" : ".md";
+    const sourcePath = join(tempDir, `stdin${ext}`);
+    writeFileSync(sourcePath, stdinContent);
+    return { sourcePath, tempDir };
+  } catch (error) {
+    return {
+      error: `Failed to write stdin content: ${error instanceof Error ? error.message : String(error)}`
+    };
   }
 }
-function addIdentifierFields(lines, item) {
-  if (item.DOI) {
-    lines.push(formatField("doi", item.DOI));
+function buildNewFulltext(currentFulltext, fileType, filename) {
+  const newFulltext = {};
+  if (currentFulltext.pdf) newFulltext.pdf = currentFulltext.pdf;
+  if (currentFulltext.markdown) newFulltext.markdown = currentFulltext.markdown;
+  newFulltext[fileType] = filename;
+  return newFulltext;
+}
+function resolveFileType(explicitType, filePath, stdinContent) {
+  let fileType = explicitType;
+  if (!fileType && filePath) {
+    fileType = detectType(filePath);
   }
-  if (item.URL) {
-    lines.push(formatField("url", item.URL));
+  if (stdinContent && !fileType) {
+    return {
+      error: "File type must be specified with --pdf or --markdown when reading from stdin."
+    };
   }
-  if (item.PMID) {
-    lines.push(formatField("note", `PMID: ${item.PMID}`));
-  } else if (item.PMCID) {
-    lines.push(formatField("note", `PMCID: ${item.PMCID}`));
+  if (!fileType) {
+    return { error: "Cannot detect file type. Use --pdf or --markdown to specify the type." };
   }
+  return fileType;
 }
-function formatSingleBibtexEntry(ref) {
-  const item = ref.getItem();
-  const entryType = mapEntryType(item.type);
-  const lines = [];
-  lines.push(`@${entryType}{${item.id},`);
-  addBasicFields(lines, item);
-  addPublicationDetails(lines, item, entryType);
-  addIdentifierFields(lines, item);
-  lines.push("}");
-  return lines.join("\n");
+async function executeFulltextAttach(options, context) {
+  const {
+    identifier,
+    filePath,
+    type: explicitType,
+    move,
+    force,
+    byUuid = false,
+    fulltextDirectory,
+    stdinContent
+  } = options;
+  const item = await findReference(identifier, context, byUuid);
+  if (!item) {
+    return { success: false, error: `Reference '${identifier}' not found` };
+  }
+  const fileTypeResult = resolveFileType(explicitType, filePath, stdinContent);
+  if (typeof fileTypeResult === "object" && "error" in fileTypeResult) {
+    return { success: false, error: fileTypeResult.error };
+  }
+  const fileType = fileTypeResult;
+  let sourcePath = filePath;
+  let tempDir;
+  if (stdinContent) {
+    const stdinResult = prepareStdinSource(stdinContent, fileType);
+    if ("error" in stdinResult) {
+      return { success: false, error: stdinResult.error };
+    }
+    sourcePath = stdinResult.sourcePath;
+    tempDir = stdinResult.tempDir;
+  }
+  if (!sourcePath) {
+    return { success: false, error: "No file path or stdin content provided." };
+  }
+  const manager = new FulltextManager(fulltextDirectory);
+  try {
+    const attachOptions = {
+      ...move !== void 0 && { move },
+      ...force !== void 0 && { force }
+    };
+    const result = await manager.attachFile(item, sourcePath, fileType, attachOptions);
+    if (result.existingFile && !result.overwritten) {
+      await cleanupTempDir(tempDir);
+      return { success: false, existingFile: result.existingFile, requiresConfirmation: true };
+    }
+    const newFulltext = buildNewFulltext(item.custom?.fulltext ?? {}, fileType, result.filename);
+    await updateFulltextMetadata(identifier, newFulltext, context, byUuid);
+    await cleanupTempDir(tempDir);
+    return {
+      success: true,
+      filename: result.filename,
+      type: fileType,
+      overwritten: result.overwritten
+    };
+  } catch (error) {
+    await cleanupTempDir(tempDir);
+    if (error instanceof FulltextIOError) {
+      return { success: false, error: error.message };
+    }
+    throw error;
+  }
 }
-function formatBibtex(references) {
-  if (references.length === 0) {
-    return "";
+async function getFileContent(manager, item, type, identifier) {
+  const filePath = manager.getFilePath(item, type);
+  if (!filePath) {
+    return { success: false, error: `No ${type} fulltext attached to '${identifier}'` };
+  }
+  try {
+    const content = await readFile(filePath);
+    return { success: true, content };
+  } catch (error) {
+    return {
+      success: false,
+      error: `Failed to read file: ${error instanceof Error ? error.message : String(error)}`
+    };
   }
-  return references.map(formatSingleBibtexEntry).join("\n\n");
 }
-function formatJson(references) {
-  const items = references.map((ref) => ref.getItem());
-  return JSON.stringify(items);
+function getFilePaths(manager, item, types, identifier) {
+  const paths = {};
+  for (const t of types) {
+    const filePath = manager.getFilePath(item, t);
+    if (filePath) {
+      paths[t] = filePath;
+    }
+  }
+  if (Object.keys(paths).length === 0) {
+    return { success: false, error: `No fulltext attached to '${identifier}'` };
+  }
+  return { success: true, paths };
 }
-function formatAuthor(author) {
-  const family = author.family || "";
-  const givenInitial = author.given ? `${author.given.charAt(0)}.` : "";
-  return givenInitial ? `${family}, ${givenInitial}` : family;
+async function executeFulltextGet(options, context) {
+  const { identifier, type, stdout: stdout2, byUuid = false, fulltextDirectory } = options;
+  const item = await findReference(identifier, context, byUuid);
+  if (!item) {
+    return { success: false, error: `Reference '${identifier}' not found` };
+  }
+  const manager = new FulltextManager(fulltextDirectory);
+  if (stdout2 && type) {
+    return getFileContent(manager, item, type, identifier);
+  }
+  const attachedTypes = type ? [type] : manager.getAttachedTypes(item);
+  if (attachedTypes.length === 0) {
+    return { success: false, error: `No fulltext attached to '${identifier}'` };
+  }
+  return getFilePaths(manager, item, attachedTypes, identifier);
 }
-function formatAuthors(authors) {
-  return authors.map(formatAuthor).join("; ");
+async function performDetachOperations(manager, item, typesToDetach, deleteFile) {
+  const detached = [];
+  const deleted = [];
+  for (const t of typesToDetach) {
+    const detachOptions = deleteFile ? { delete: deleteFile } : {};
+    const result = await manager.detachFile(item, t, detachOptions);
+    detached.push(t);
+    if (result.deleted) {
+      deleted.push(t);
+    }
+  }
+  return { detached, deleted };
 }
-function formatSingleReference(ref) {
-  const item = ref.getItem();
-  const lines = [];
-  const header = item.title ? `[${item.id}] ${item.title}` : `[${item.id}]`;
-  lines.push(header);
-  if (item.author && item.author.length > 0) {
-    lines.push(`  Authors: ${formatAuthors(item.author)}`);
+function buildRemainingFulltext(currentFulltext, detached) {
+  const newFulltext = {};
+  if (currentFulltext.pdf && !detached.includes("pdf")) {
+    newFulltext.pdf = currentFulltext.pdf;
   }
-  const year = item.issued?.["date-parts"]?.[0]?.[0];
-  lines.push(`  Year: ${year || "(no year)"}`);
-  lines.push(`  Type: ${item.type}`);
-  if (item.DOI) {
-    lines.push(`  DOI: ${item.DOI}`);
+  if (currentFulltext.markdown && !detached.includes("markdown")) {
+    newFulltext.markdown = currentFulltext.markdown;
   }
-  if (item.PMID) {
-    lines.push(`  PMID: ${item.PMID}`);
+  return Object.keys(newFulltext).length > 0 ? newFulltext : void 0;
+}
+function handleDetachError(error) {
+  if (error instanceof FulltextNotAttachedError || error instanceof FulltextIOError) {
+    return { success: false, error: error.message };
+  }
+  throw error;
+}
+async function executeFulltextDetach(options, context) {
+  const { identifier, type, delete: deleteFile, byUuid = false, fulltextDirectory } = options;
+  const item = await findReference(identifier, context, byUuid);
+  if (!item) {
+    return { success: false, error: `Reference '${identifier}' not found` };
+  }
+  const manager = new FulltextManager(fulltextDirectory);
+  const typesToDetach = type ? [type] : manager.getAttachedTypes(item);
+  if (typesToDetach.length === 0) {
+    return { success: false, error: `No fulltext attached to '${identifier}'` };
+  }
+  try {
+    const { detached, deleted } = await performDetachOperations(
+      manager,
+      item,
+      typesToDetach,
+      deleteFile
+    );
+    const updatedFulltext = buildRemainingFulltext(item.custom?.fulltext ?? {}, detached);
+    await updateFulltextMetadata(identifier, updatedFulltext, context, byUuid);
+    const resultData = { success: true, detached };
+    if (deleted.length > 0) {
+      resultData.deleted = deleted;
+    }
+    return resultData;
+  } catch (error) {
+    return handleDetachError(error);
+  }
+}
+function formatFulltextAttachOutput(result) {
+  if (result.requiresConfirmation) {
+    return `File already attached: ${result.existingFile}
+Use --force to overwrite.`;
+  }
+  if (!result.success) {
+    return `Error: ${result.error}`;
+  }
+  const parts = [];
+  if (result.overwritten) {
+    parts.push(`Attached ${result.type} (overwritten): ${result.filename}`);
+  } else {
+    parts.push(`Attached ${result.type}: ${result.filename}`);
+  }
+  return parts.join("\n");
+}
+function formatFulltextGetOutput(result) {
+  if (!result.success) {
+    return `Error: ${result.error}`;
   }
-  if (item.PMCID) {
-    lines.push(`  PMCID: ${item.PMCID}`);
+  if (result.content) {
+    return result.content.toString();
   }
-  if (item.URL) {
-    lines.push(`  URL: ${item.URL}`);
+  const lines = [];
+  if (result.paths?.pdf) {
+    lines.push(`pdf: ${result.paths.pdf}`);
+  }
+  if (result.paths?.markdown) {
+    lines.push(`markdown: ${result.paths.markdown}`);
   }
-  lines.push(`  UUID: ${ref.getUuid()}`);
   return lines.join("\n");
 }
-function formatPretty(references) {
-  if (references.length === 0) {
-    return "";
+function formatFulltextDetachOutput(result) {
+  if (!result.success) {
+    return `Error: ${result.error}`;
   }
-  return references.map(formatSingleReference).join("\n\n");
+  const lines = [];
+  for (const type of result.detached ?? []) {
+    if (result.deleted?.includes(type)) {
+      lines.push(`Detached and deleted ${type}`);
+    } else {
+      lines.push(`Detached ${type}`);
+    }
+  }
+  return lines.join("\n");
+}
+function getFulltextExitCode(result) {
+  return result.success ? 0 : 1;
+}
+function getListFormat(options) {
+  if (options.json) return "json";
+  if (options.idsOnly) return "ids-only";
+  if (options.uuid) return "uuid";
+  if (options.bibtex) return "bibtex";
+  return "pretty";
 }
-async function list(items, options) {
+function validateOptions$1(options) {
   const outputOptions = [options.json, options.idsOnly, options.uuid, options.bibtex].filter(
     Boolean
   );
@@ -261,28 +699,81 @@ async function list(items, options) {
       "Multiple output formats specified. Only one of --json, --ids-only, --uuid, --bibtex can be used."
     );
   }
-  const references = items.map((item) => new Reference(item));
-  if (options.json) {
-    process.stdout.write(formatJson(references));
-  } else if (options.idsOnly) {
-    for (const item of items) {
-      process.stdout.write(`${item.id}
-`);
-    }
-  } else if (options.uuid) {
-    for (const item of items) {
-      if (item.custom) {
-        process.stdout.write(`${item.custom.uuid}
-`);
-      }
+}
+async function executeList(options, context) {
+  validateOptions$1(options);
+  const format = getListFormat(options);
+  if (context.type === "server") {
+    return context.client.list({ format });
+  }
+  return listReferences(context.library, { format });
+}
+function formatListOutput(result) {
+  if (result.items.length === 0) {
+    return "";
+  }
+  return result.items.join("\n");
+}
+async function executeRemove(options, context) {
+  const { identifier, byUuid = false } = options;
+  if (context.type === "server") {
+    return context.client.remove(identifier, { byUuid });
+  }
+  return removeReference(context.library, { identifier, byUuid });
+}
+function formatRemoveOutput(result, identifier) {
+  if (!result.removed) {
+    return `Reference not found: ${identifier}`;
+  }
+  const item = result.item;
+  if (item) {
+    return `Removed: [${item.id}] ${item.title || "(no title)"}`;
+  }
+  return `Removed reference: ${identifier}`;
+}
+function getFulltextAttachmentTypes(item) {
+  const types = [];
+  const fulltext = item.custom?.fulltext;
+  if (fulltext?.pdf) {
+    types.push("pdf");
+  }
+  if (fulltext?.markdown) {
+    types.push("markdown");
+  }
+  return types;
+}
+function formatFulltextWarning(types) {
+  const typeLabels = types.map((t) => t === "pdf" ? "PDF" : "Markdown");
+  const fileTypes = typeLabels.join(" and ");
+  return `Warning: This reference has fulltext files attached (${fileTypes}). Use --force to also delete the fulltext files.`;
+}
+async function deleteFulltextFiles(item, fulltextDirectory) {
+  const fulltext = item.custom?.fulltext;
+  if (!fulltext) {
+    return;
+  }
+  const filesToDelete = [];
+  if (fulltext.pdf) {
+    filesToDelete.push(join(fulltextDirectory, fulltext.pdf));
+  }
+  if (fulltext.markdown) {
+    filesToDelete.push(join(fulltextDirectory, fulltext.markdown));
+  }
+  for (const filePath of filesToDelete) {
+    try {
+      await unlink(filePath);
+    } catch {
     }
-  } else if (options.bibtex) {
-    process.stdout.write(formatBibtex(references));
-  } else {
-    process.stdout.write(formatPretty(references));
   }
 }
-async function search(items, query, options) {
+function getSearchFormat(options) {
+  if (options.json) return "json";
+  if (options.idsOnly) return "ids-only";
+  if (options.uuid) return "uuid";
+  if (options.bibtex) return "bibtex";
+  return "pretty";
+}
+function validateOptions(options) {
   const outputOptions = [options.json, options.idsOnly, options.uuid, options.bibtex].filter(
     Boolean
   );
@@ -291,30 +782,20 @@ async function search(items, query, options) {
       "Multiple output formats specified. Only one of --json, --ids-only, --uuid, --bibtex can be used."
     );
   }
-  const searchQuery = tokenize(query);
-  const results = search$1(items, searchQuery.tokens);
-  const sorted = sortResults(results);
-  const matchedItems = sorted.map((result) => result.reference);
-  const references = matchedItems.map((item) => new Reference(item));
-  if (options.json) {
-    process.stdout.write(formatJson(references));
-  } else if (options.idsOnly) {
-    for (const item of matchedItems) {
-      process.stdout.write(`${item.id}
-`);
-    }
-  } else if (options.uuid) {
-    for (const item of matchedItems) {
-      if (item.custom) {
-        process.stdout.write(`${item.custom.uuid}
-`);
-      }
-    }
-  } else if (options.bibtex) {
-    process.stdout.write(formatBibtex(references));
-  } else {
-    process.stdout.write(formatPretty(references));
+}
+async function executeSearch(options, context) {
+  validateOptions(options);
+  const format = getSearchFormat(options);
+  if (context.type === "server") {
+    return context.client.search({ query: options.query, format });
+  }
+  return searchReferences(context.library, { query: options.query, format });
+}
+function formatSearchOutput(result) {
+  if (result.items.length === 0) {
+    return "";
   }
+  return result.items.join("\n");
 }
 async function serverStart(options) {
   const existingStatus = await serverStatus(options.portfilePath);
@@ -353,117 +834,31 @@ async function serverStatus(portfilePath) {
   }
   return result;
 }
-async function update(items, identifier, updates, options) {
-  let foundIndex = -1;
-  if (options.byUuid) {
-    foundIndex = items.findIndex((item) => item.custom?.uuid === identifier);
-  } else {
-    foundIndex = items.findIndex((item) => item.id === identifier);
-  }
-  if (foundIndex === -1) {
-    return {
-      updated: false,
-      items
-    };
+async function executeUpdate(options, context) {
+  const { identifier, updates, byUuid = false } = options;
+  if (context.type === "server") {
+    return context.client.update(identifier, updates, { byUuid });
   }
-  const existingItem = items[foundIndex];
-  if (!existingItem) {
-    return {
-      updated: false,
-      items
-    };
-  }
-  const updatedItem = {
-    ...existingItem,
-    ...updates,
-    // Ensure required fields
-    id: updates.id ?? existingItem.id,
-    type: updates.type ?? existingItem.type,
-    // Preserve UUID and created_at
-    custom: {
-      ...existingItem.custom || {},
-      ...updates.custom || {},
-      uuid: existingItem.custom?.uuid || "",
-      created_at: existingItem.custom?.created_at || (/* @__PURE__ */ new Date()).toISOString(),
-      // Update timestamp
-      timestamp: (/* @__PURE__ */ new Date()).toISOString()
-    }
-  };
-  const updatedItems = [...items.slice(0, foundIndex), updatedItem, ...items.slice(foundIndex + 1)];
-  return {
-    updated: true,
-    item: updatedItem,
-    items: updatedItems
-  };
+  return updateReference(context.library, { identifier, updates, byUuid });
 }
-async function readJsonInput(file) {
-  if (file) {
-    try {
-      return readFileSync(file, "utf-8");
-    } catch (error) {
-      throw new Error(
-        `I/O error: Cannot read file ${file}: ${error instanceof Error ? error.message : String(error)}`
-      );
+function formatUpdateOutput(result, identifier) {
+  if (!result.updated) {
+    if (result.idCollision) {
+      return `Update failed: ID collision for ${identifier}`;
     }
+    return `Reference not found: ${identifier}`;
   }
-  const chunks = [];
-  for await (const chunk of stdin) {
-    chunks.push(chunk);
-  }
-  return Buffer.concat(chunks).toString("utf-8");
-}
-function parseJsonInput(input) {
-  if (!input || input.trim() === "") {
-    throw new Error("Parse error: Empty input");
-  }
-  try {
-    return JSON.parse(input);
-  } catch (error) {
-    throw new Error(
-      `Parse error: Invalid JSON: ${error instanceof Error ? error.message : String(error)}`
-    );
-  }
-}
-async function loadConfigWithOverrides(options) {
-  const config = await loadConfig();
-  const overrides = {};
-  if (options.library) {
-    overrides.library = options.library;
-  }
-  if (options.quiet) {
-    overrides.logLevel = "silent";
-  } else if (options.verbose) {
-    overrides.logLevel = "debug";
-  } else if (options.logLevel) {
-    overrides.logLevel = options.logLevel;
+  const item = result.item;
+  const parts = [];
+  if (item) {
+    parts.push(`Updated: [${item.id}] ${item.title || "(no title)"}`);
+  } else {
+    parts.push(`Updated reference: ${identifier}`);
   }
-  if (options.backup !== void 0 || options.backupDir) {
-    overrides.backup = {
-      ...config.backup,
-      ...options.backup !== void 0 && { enabled: options.backup },
-      ...options.backupDir && { directory: options.backupDir }
-    };
+  if (result.idChanged && result.newId) {
+    parts.push(`ID changed to: ${result.newId}`);
   }
-  return { ...config, ...overrides };
-}
-function isTTY() {
-  return Boolean(stdin.isTTY && stdout.isTTY);
-}
-async function readConfirmation(prompt) {
-  if (!isTTY()) {
-    return true;
-  }
-  stdout.write(`${prompt} (y/N): `);
-  const chunks = [];
-  for await (const chunk of stdin) {
-    chunks.push(chunk);
-    const input2 = Buffer.concat(chunks).toString("utf-8");
-    if (input2.includes("\n")) {
-      break;
-    }
-  }
-  const input = Buffer.concat(chunks).toString("utf-8").trim().toLowerCase();
-  return input === "y" || input === "yes";
+  return parts.join("\n");
 }
 class ServerClient {
   constructor(baseUrl) {
@@ -482,12 +877,15 @@ class ServerClient {
     return await response.json();
   }
   /**
-   * Find reference by UUID.
-   * @param uuid - Reference UUID
+   * Find reference by identifier.
+   * @param identifier - Citation ID or UUID
+   * @param options - Options object
+   * @param options.byUuid - If true, treat identifier as UUID; otherwise as citation ID
    * @returns CSL item or null if not found
    */
-  async findByUuid(uuid) {
-    const url = `${this.baseUrl}/api/references/${uuid}`;
+  async find(identifier, options) {
+    const path2 = options?.byUuid ? `/api/references/uuid/${identifier}` : `/api/references/id/${identifier}`;
+    const url = `${this.baseUrl}${path2}`;
     const response = await fetch(url);
     if (response.status === 404) {
       return null;
@@ -516,34 +914,111 @@ class ServerClient {
   }
   /**
    * Update existing reference.
-   * @param uuid - Reference UUID
-   * @param item - Updated CSL item
-   * @returns Updated CSL item
+   * @param identifier - Citation ID or UUID
+   * @param updates - Partial CSL item with fields to update
+   * @param options - Options object
+   * @param options.byUuid - If true, treat identifier as UUID; otherwise as citation ID
+   * @returns Update operation result
    */
-  async update(uuid, item) {
-    const url = `${this.baseUrl}/api/references/${uuid}`;
+  async update(identifier, updates, options) {
+    const path2 = options?.byUuid ? `/api/references/uuid/${identifier}` : `/api/references/id/${identifier}`;
+    const url = `${this.baseUrl}${path2}`;
     const response = await fetch(url, {
       method: "PUT",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(item)
+      body: JSON.stringify(updates)
     });
-    if (!response.ok) {
+    if (!response.ok && response.status !== 404 && response.status !== 409) {
       throw new Error(await response.text());
     }
     return await response.json();
   }
   /**
-   * Remove reference by UUID.
-   * @param uuid - Reference UUID
+   * Remove reference by identifier.
+   * @param identifier - Citation ID or UUID
+   * @param options - Options object
+   * @param options.byUuid - If true, treat identifier as UUID; otherwise as citation ID
+   * @returns Remove operation result
    */
-  async remove(uuid) {
-    const url = `${this.baseUrl}/api/references/${uuid}`;
+  async remove(identifier, options) {
+    const path2 = options?.byUuid ? `/api/references/uuid/${identifier}` : `/api/references/id/${identifier}`;
+    const url = `${this.baseUrl}${path2}`;
     const response = await fetch(url, {
       method: "DELETE"
     });
+    if (!response.ok && response.status !== 404) {
+      throw new Error(await response.text());
+    }
+    return await response.json();
+  }
+  /**
+   * Add references from various input formats.
+   * @param inputs - Array of inputs (file paths, PMIDs, DOIs)
+   * @param options - Options for add operation
+   * @returns Result containing added, failed, and skipped items
+   */
+  async addFromInputs(inputs, options) {
+    const url = `${this.baseUrl}/api/add`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ inputs, options })
+    });
+    if (!response.ok) {
+      throw new Error(await response.text());
+    }
+    return await response.json();
+  }
+  /**
+   * Generate citations for references.
+   * @param options - Cite options including identifiers and formatting
+   * @returns Cite result with per-identifier results
+   */
+  async cite(options) {
+    const url = `${this.baseUrl}/api/cite`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(options)
+    });
+    if (!response.ok) {
+      throw new Error(await response.text());
+    }
+    return await response.json();
+  }
+  /**
+   * List all references with optional formatting.
+   * @param options - List options including format
+   * @returns List result with formatted items
+   */
+  async list(options) {
+    const url = `${this.baseUrl}/api/list`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(options ?? {})
+    });
     if (!response.ok) {
       throw new Error(await response.text());
     }
+    return await response.json();
+  }
+  /**
+   * Search references with query.
+   * @param options - Search options including query and format
+   * @returns Search result with formatted items
+   */
+  async search(options) {
+    const url = `${this.baseUrl}/api/search`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(options)
+    });
+    if (!response.ok) {
+      throw new Error(await response.text());
+    }
+    return await response.json();
   }
 }
 async function getServerConnection(libraryPath, config) {
@@ -557,48 +1032,139 @@ async function getServerConnection(libraryPath, config) {
     }
     return null;
   }
-  if (!isProcessRunning(portfileData.pid)) {
-    await removePortfile(portfilePath);
-    return null;
+  if (!isProcessRunning(portfileData.pid)) {
+    await removePortfile(portfilePath);
+    return null;
+  }
+  if (!portfileData.library || portfileData.library !== libraryPath) {
+    return null;
+  }
+  return {
+    baseUrl: `http://localhost:${portfileData.port}`,
+    pid: portfileData.pid
+  };
+}
+async function startServerDaemon(libraryPath, _config) {
+  const binaryPath = process.argv[1] || process.execPath;
+  const child = spawn(
+    process.execPath,
+    [binaryPath, "server", "start", "--daemon", "--library", libraryPath],
+    {
+      detached: true,
+      stdio: "ignore"
+    }
+  );
+  child.unref();
+}
+async function waitForPortfile(timeoutMs) {
+  const portfilePath = getPortfilePath();
+  const startTime = Date.now();
+  const checkInterval = 50;
+  while (Date.now() - startTime < timeoutMs) {
+    if (await portfileExists(portfilePath)) {
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, checkInterval));
+  }
+  throw new Error(`Server failed to start: portfile not created within ${timeoutMs}ms`);
+}
+async function createExecutionContext(config, loadLibrary) {
+  const server = await getServerConnection(config.library, config);
+  if (server) {
+    return {
+      type: "server",
+      client: new ServerClient(server.baseUrl)
+    };
+  }
+  const library = await loadLibrary(config.library);
+  return {
+    type: "local",
+    library
+  };
+}
+async function readJsonInput(file) {
+  if (file) {
+    try {
+      return readFileSync(file, "utf-8");
+    } catch (error) {
+      throw new Error(
+        `I/O error: Cannot read file ${file}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  const chunks = [];
+  for await (const chunk of stdin) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+}
+function parseJsonInput(input) {
+  if (!input || input.trim() === "") {
+    throw new Error("Parse error: Empty input");
+  }
+  try {
+    return JSON.parse(input);
+  } catch (error) {
+    throw new Error(
+      `Parse error: Invalid JSON: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+async function loadConfigWithOverrides(options) {
+  const config = await loadConfig();
+  const overrides = {};
+  if (options.library) {
+    overrides.library = options.library;
+  }
+  if (options.quiet) {
+    overrides.logLevel = "silent";
+  } else if (options.verbose) {
+    overrides.logLevel = "debug";
+  } else if (options.logLevel) {
+    overrides.logLevel = options.logLevel;
   }
-  if (!portfileData.library || portfileData.library !== libraryPath) {
-    return null;
+  if (options.backup !== void 0 || options.backupDir) {
+    overrides.backup = {
+      ...config.backup,
+      ...options.backup !== void 0 && { enabled: options.backup },
+      ...options.backupDir && { directory: options.backupDir }
+    };
   }
-  return {
-    baseUrl: `http://localhost:${portfileData.port}`,
-    pid: portfileData.pid
-  };
+  return { ...config, ...overrides };
 }
-async function startServerDaemon(libraryPath, _config) {
-  const binaryPath = process.argv[1] || process.execPath;
-  const child = spawn(
-    process.execPath,
-    [binaryPath, "server", "start", "--daemon", "--library", libraryPath],
-    {
-      detached: true,
-      stdio: "ignore"
-    }
-  );
-  child.unref();
+function isTTY() {
+  return Boolean(stdin.isTTY && stdout.isTTY);
 }
-async function waitForPortfile(timeoutMs) {
-  const portfilePath = getPortfilePath();
-  const startTime = Date.now();
-  const checkInterval = 50;
-  while (Date.now() - startTime < timeoutMs) {
-    if (await portfileExists(portfilePath)) {
-      return;
+async function readConfirmation(prompt) {
+  if (!isTTY()) {
+    return true;
+  }
+  stdout.write(`${prompt} (y/N): `);
+  const chunks = [];
+  for await (const chunk of stdin) {
+    chunks.push(chunk);
+    const input2 = Buffer.concat(chunks).toString("utf-8");
+    if (input2.includes("\n")) {
+      break;
     }
-    await new Promise((resolve) => setTimeout(resolve, checkInterval));
   }
-  throw new Error(`Server failed to start: portfile not created within ${timeoutMs}ms`);
+  const input = Buffer.concat(chunks).toString("utf-8").trim().toLowerCase();
+  return input === "y" || input === "yes";
+}
+async function readStdinContent() {
+  const chunks = [];
+  for await (const chunk of stdin) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf-8").trim();
+}
+async function readStdinBuffer() {
+  const chunks = [];
+  for await (const chunk of stdin) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks);
 }
-const version = "0.1.0";
-const description = "A local reference management tool using CSL-JSON as the single source of truth";
-const packageJson = {
-  version,
-  description
-};
 function createProgram() {
   const program = new Command();
   program.name("reference-manager").version(packageJson.version).description(packageJson.description);
@@ -608,175 +1174,129 @@ function createProgram() {
   registerAddCommand(program);
   registerRemoveCommand(program);
   registerUpdateCommand(program);
+  registerCiteCommand(program);
   registerServerCommand(program);
+  registerFulltextCommand(program);
   return program;
 }
-function registerListCommand(program) {
-  program.command("list").description("List all references in the library").option("--json", "Output in JSON format").option("--ids-only", "Output only citation keys").option("--uuid", "Output only UUIDs").option("--bibtex", "Output in BibTeX format").action(async (options) => {
-    try {
-      const globalOpts = program.opts();
-      const config = await loadConfigWithOverrides({ ...globalOpts, ...options });
-      const server = await getServerConnection(config.library, config);
-      let items;
-      if (server) {
-        const client = new ServerClient(server.baseUrl);
-        items = await client.getAll();
-      } else {
-        const library = await Library.load(config.library);
-        items = library.getAll().map((ref) => ref.getItem());
-      }
-      await list(items, {
-        json: options.json,
-        idsOnly: options.idsOnly,
-        uuid: options.uuid,
-        bibtex: options.bibtex
-      });
-      process.exit(0);
-    } catch (error) {
-      process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
+async function handleListAction(options, program) {
+  try {
+    const globalOpts = program.opts();
+    const config = await loadConfigWithOverrides({ ...globalOpts, ...options });
+    const context = await createExecutionContext(config, Library.load);
+    const result = await executeList(options, context);
+    const output = formatListOutput(result);
+    if (output) {
+      process.stdout.write(`${output}
 `);
-      process.exit(4);
     }
-  });
-}
-function registerSearchCommand(program) {
-  program.command("search").description("Search references").argument("<query>", "Search query").option("--json", "Output in JSON format").option("--ids-only", "Output only citation keys").option("--uuid", "Output only UUIDs").option("--bibtex", "Output in BibTeX format").action(async (query, options) => {
-    try {
-      const globalOpts = program.opts();
-      const config = await loadConfigWithOverrides({ ...globalOpts, ...options });
-      const server = await getServerConnection(config.library, config);
-      let items;
-      if (server) {
-        const client = new ServerClient(server.baseUrl);
-        items = await client.getAll();
-      } else {
-        const library = await Library.load(config.library);
-        items = library.getAll().map((ref) => ref.getItem());
-      }
-      await search(items, query, {
-        json: options.json,
-        idsOnly: options.idsOnly,
-        uuid: options.uuid,
-        bibtex: options.bibtex
-      });
-      process.exit(0);
-    } catch (error) {
-      process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
+    process.exit(0);
+  } catch (error) {
+    process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
 `);
-      process.exit(4);
-    }
+    process.exit(4);
+  }
+}
+function registerListCommand(program) {
+  program.command("list").description("List all references in the library").option("--json", "Output in JSON format").option("--ids-only", "Output only citation keys").option("--uuid", "Output only UUIDs").option("--bibtex", "Output in BibTeX format").action(async (options) => {
+    await handleListAction(options, program);
   });
 }
-async function addViaServer(items, server, force) {
-  const client = new ServerClient(server.baseUrl);
-  for (const item of items) {
-    try {
-      await client.add(item);
-      process.stderr.write(`Added reference: [${item.id}]
-`);
-    } catch (error) {
-      if (!force && error instanceof Error && error.message.includes("Duplicate")) {
-        process.stderr.write(`Error: ${error.message}
+async function handleSearchAction(query, options, program) {
+  try {
+    const globalOpts = program.opts();
+    const config = await loadConfigWithOverrides({ ...globalOpts, ...options });
+    const context = await createExecutionContext(config, Library.load);
+    const result = await executeSearch({ ...options, query }, context);
+    const output = formatSearchOutput(result);
+    if (output) {
+      process.stdout.write(`${output}
 `);
-        process.exit(1);
-      }
-      throw error;
     }
-  }
-}
-async function addViaLibrary(items, libraryPath, force) {
-  const library = await Library.load(libraryPath);
-  const existingItems = library.getAll().map((ref) => ref.getItem());
-  for (const item of items) {
-    const result = await add(existingItems, item, { force });
-    if (result.added) {
-      library.add(result.item);
-      process.stderr.write(`Added reference: [${result.item.id}]
+    process.exit(0);
+  } catch (error) {
+    process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
 `);
-      existingItems.push(result.item);
-    } else if (result.duplicate) {
-      throw new Error(
-        `Duplicate detected: ${result.duplicate.type} match with existing reference [${result.duplicate.existing.id}]`
-      );
-    }
+    process.exit(4);
   }
-  await library.save();
 }
-function handleAddError(error) {
-  const message = error instanceof Error ? error.message : String(error);
-  if (message.includes("Parse error")) {
-    process.stderr.write(`Error: ${message}
-`);
-    process.exit(3);
-  }
-  if (message.includes("Duplicate")) {
-    process.stderr.write(`Error: ${message}
-`);
-    process.exit(1);
-  }
-  process.stderr.write(`Error: ${message}
-`);
-  process.exit(4);
+function registerSearchCommand(program) {
+  program.command("search").description("Search references").argument("<query>", "Search query").option("--json", "Output in JSON format").option("--ids-only", "Output only citation keys").option("--uuid", "Output only UUIDs").option("--bibtex", "Output in BibTeX format").action(async (query, options) => {
+    await handleSearchAction(query, options, program);
+  });
 }
-async function handleAddAction(file, options, program) {
+async function handleAddAction(inputs, options, program) {
   try {
     const globalOpts = program.opts();
     const config = await loadConfigWithOverrides({ ...globalOpts, ...options });
-    const inputStr = await readJsonInput(file);
-    const input = parseJsonInput(inputStr);
-    const items = Array.isArray(input) ? input : [input];
-    const server = await getServerConnection(config.library, config);
-    if (server) {
-      await addViaServer(items, server, options.force ?? false);
-    } else {
-      await addViaLibrary(items, config.library, options.force ?? false);
+    let stdinContent;
+    if (inputs.length === 0) {
+      stdinContent = await readStdinContent();
     }
-    process.exit(0);
+    const context = await createExecutionContext(config, Library.load);
+    const addOptions = {
+      inputs,
+      force: options.force ?? false
+    };
+    if (options.format !== void 0) {
+      addOptions.format = options.format;
+    }
+    if (options.verbose !== void 0) {
+      addOptions.verbose = options.verbose;
+    }
+    if (stdinContent?.trim()) {
+      addOptions.stdinContent = stdinContent;
+    }
+    const pubmedConfig = {};
+    if (config.pubmed.email !== void 0) {
+      pubmedConfig.email = config.pubmed.email;
+    }
+    if (config.pubmed.apiKey !== void 0) {
+      pubmedConfig.apiKey = config.pubmed.apiKey;
+    }
+    if (Object.keys(pubmedConfig).length > 0) {
+      addOptions.pubmedConfig = pubmedConfig;
+    }
+    const result = await executeAdd(addOptions, context);
+    const output = formatAddOutput(result, options.verbose ?? false);
+    process.stderr.write(`${output}
+`);
+    process.exit(getExitCode(result));
   } catch (error) {
-    handleAddError(error);
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`Error: ${message}
+`);
+    process.exit(1);
   }
 }
 function registerAddCommand(program) {
-  program.command("add").description("Add new reference(s) to the library").argument("[file]", "JSON file to add (or use stdin)").option("-f, --force", "Skip duplicate detection").action(async (file, options) => {
-    await handleAddAction(file, options, program);
+  program.command("add").description("Add new reference(s) to the library").argument("[input...]", "File paths or identifiers (PMID/DOI), or use stdin").option("-f, --force", "Skip duplicate detection").option("--format <format>", "Explicit input format: json|bibtex|ris|pmid|doi|auto", "auto").option("--verbose", "Show detailed error information").action(async (inputs, options) => {
+    await handleAddAction(inputs, options, program);
   });
 }
-async function findReferenceToRemove(identifier, byUuid, server, libraryPath) {
-  if (server) {
-    const client = new ServerClient(server.baseUrl);
-    const items = await client.getAll();
-    return byUuid ? items.find((item) => item.custom?.uuid === identifier) : items.find((item) => item.id === identifier);
+async function findReferenceToRemove(identifier, byUuid, context) {
+  if (context.type === "server") {
+    const item = await context.client.find(identifier, { byUuid });
+    return item ?? void 0;
   }
-  const library = await Library.load(libraryPath);
-  const ref = byUuid ? library.findByUuid(identifier) : library.findById(identifier);
+  const ref = byUuid ? context.library.findByUuid(identifier) : context.library.findById(identifier);
   return ref?.getItem();
 }
-async function confirmRemoval(refToRemove, force) {
+async function confirmRemoval(refToRemove, force, fulltextWarning) {
   if (force || !isTTY()) {
     return true;
   }
   const authors = Array.isArray(refToRemove.author) ? refToRemove.author.map((a) => `${a.family || ""}, ${a.given?.[0] || ""}.`).join("; ") : "(no authors)";
-  const confirmMsg = `Remove reference [${refToRemove.id}]?
+  let confirmMsg = `Remove reference [${refToRemove.id}]?
 Title: ${refToRemove.title || "(no title)"}
-Authors: ${authors}
-Continue?`;
-  return await readConfirmation(confirmMsg);
-}
-async function removeReference(identifier, refToRemove, byUuid, server, libraryPath) {
-  if (server) {
-    const client = new ServerClient(server.baseUrl);
-    if (!refToRemove.custom?.uuid) {
-      throw new Error("Reference missing UUID");
-    }
-    await client.remove(refToRemove.custom.uuid);
-    return;
-  }
-  const library = await Library.load(libraryPath);
-  const removed = byUuid ? library.removeByUuid(identifier) : library.removeById(identifier);
-  if (!removed) {
-    throw new Error("Reference not found");
+Authors: ${authors}`;
+  if (fulltextWarning) {
+    confirmMsg += `
+
+${fulltextWarning}`;
   }
-  await library.save();
+  confirmMsg += "\nContinue?";
+  return await readConfirmation(confirmMsg);
 }
 function handleRemoveError(error) {
   const message = error instanceof Error ? error.message : String(error);
@@ -789,30 +1309,61 @@ function handleRemoveError(error) {
 `);
   process.exit(4);
 }
+function formatTypeLabels(types) {
+  return types.map((t) => t === "pdf" ? "PDF" : "Markdown").join(" and ");
+}
+async function handleFulltextDeletion(item, fulltextDirectory, types, output) {
+  await deleteFulltextFiles(item, fulltextDirectory);
+  const typeLabels = formatTypeLabels(types);
+  process.stderr.write(`${output}
+`);
+  process.stderr.write(`Deleted fulltext files: ${typeLabels}
+`);
+}
 async function handleRemoveAction(identifier, options, program) {
   try {
     const globalOpts = program.opts();
     const config = await loadConfigWithOverrides({ ...globalOpts, ...options });
-    const server = await getServerConnection(config.library, config);
-    const refToRemove = await findReferenceToRemove(
-      identifier,
-      options.uuid ?? false,
-      server,
-      config.library
-    );
+    const context = await createExecutionContext(config, Library.load);
+    const refToRemove = await findReferenceToRemove(identifier, options.uuid ?? false, context);
     if (!refToRemove) {
       process.stderr.write(`Error: Reference not found: ${identifier}
 `);
       process.exit(1);
     }
-    const confirmed = await confirmRemoval(refToRemove, options.force ?? false);
+    const fulltextTypes = getFulltextAttachmentTypes(refToRemove);
+    const hasFulltext = fulltextTypes.length > 0;
+    if (hasFulltext && !isTTY() && !options.force) {
+      const warning = formatFulltextWarning(fulltextTypes);
+      process.stderr.write(`Error: ${warning}
+`);
+      process.exit(1);
+    }
+    const fulltextWarning = hasFulltext && !options.force ? formatFulltextWarning(fulltextTypes) : void 0;
+    const confirmed = await confirmRemoval(refToRemove, options.force ?? false, fulltextWarning);
     if (!confirmed) {
       process.stderr.write("Cancelled.\n");
       process.exit(2);
     }
-    await removeReference(identifier, refToRemove, options.uuid ?? false, server, config.library);
-    process.stderr.write(`Removed reference: [${refToRemove.id}]
+    const removeOptions = {
+      identifier
+    };
+    if (options.uuid !== void 0) {
+      removeOptions.byUuid = options.uuid;
+    }
+    const result = await executeRemove(removeOptions, context);
+    const output = formatRemoveOutput(result, identifier);
+    if (!result.removed) {
+      process.stderr.write(`${output}
 `);
+      process.exit(1);
+    }
+    if (hasFulltext && options.force) {
+      await handleFulltextDeletion(refToRemove, config.fulltext.directory, fulltextTypes, output);
+    } else {
+      process.stderr.write(`${output}
+`);
+    }
     process.exit(0);
   } catch (error) {
     handleRemoveError(error);
@@ -823,31 +1374,6 @@ function registerRemoveCommand(program) {
     await handleRemoveAction(identifier, options, program);
   });
 }
-async function updateViaServer(identifier, updates, byUuid, server) {
-  const client = new ServerClient(server.baseUrl);
-  const items = await client.getAll();
-  const refToUpdate = byUuid ? items.find((item) => item.custom?.uuid === identifier) : items.find((item) => item.id === identifier);
-  if (!refToUpdate || !refToUpdate.custom?.uuid) {
-    process.stderr.write(`Error: Reference not found: ${identifier}
-`);
-    process.exit(1);
-  }
-  const updatedItem = { ...refToUpdate, ...updates };
-  await client.update(refToUpdate.custom.uuid, updatedItem);
-}
-async function updateViaLibrary(identifier, updates, byUuid, libraryPath) {
-  const library = await Library.load(libraryPath);
-  const items = library.getAll().map((ref) => ref.getItem());
-  const result = await update(items, identifier, updates, { byUuid });
-  if (!result.updated || !result.item) {
-    throw new Error("Reference not found");
-  }
-  if (result.item.custom?.uuid) {
-    library.removeByUuid(result.item.custom.uuid);
-    library.add(result.item);
-  }
-  await library.save();
-}
 function handleUpdateError(error) {
   const message = error instanceof Error ? error.message : String(error);
   if (message.includes("Parse error")) {
@@ -872,20 +1398,25 @@ async function handleUpdateAction(identifier, file, options, program) {
     const updates = parseJsonInput(inputStr);
     const updatesSchema = z.record(z.string(), z.unknown());
     const validatedUpdates = updatesSchema.parse(updates);
-    const server = await getServerConnection(config.library, config);
-    if (server) {
-      await updateViaServer(identifier, validatedUpdates, options.uuid ?? false, server);
-    } else {
-      await updateViaLibrary(
-        identifier,
-        validatedUpdates,
-        options.uuid ?? false,
-        config.library
-      );
+    const context = await createExecutionContext(config, Library.load);
+    const updateOptions = {
+      identifier,
+      updates: validatedUpdates
+    };
+    if (options.uuid !== void 0) {
+      updateOptions.byUuid = options.uuid;
     }
-    process.stderr.write(`Updated reference: [${identifier}]
+    const result = await executeUpdate(updateOptions, context);
+    const output = formatUpdateOutput(result, identifier);
+    if (result.updated) {
+      process.stderr.write(`${output}
 `);
-    process.exit(0);
+      process.exit(0);
+    } else {
+      process.stderr.write(`${output}
+`);
+      process.exit(1);
+    }
   } catch (error) {
     handleUpdateError(error);
   }
@@ -895,6 +1426,34 @@ function registerUpdateCommand(program) {
     await handleUpdateAction(identifier, file, options, program);
   });
 }
+async function handleCiteAction(identifiers, options, program) {
+  try {
+    const globalOpts = program.opts();
+    const config = await loadConfigWithOverrides({ ...globalOpts, ...options });
+    const context = await createExecutionContext(config, Library.load);
+    const result = await executeCite({ ...options, identifiers }, context);
+    const output = formatCiteOutput(result);
+    if (output) {
+      process.stdout.write(`${output}
+`);
+    }
+    const errors = formatCiteErrors(result);
+    if (errors) {
+      process.stderr.write(`${errors}
+`);
+    }
+    process.exit(getCiteExitCode(result));
+  } catch (error) {
+    process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
+`);
+    process.exit(4);
+  }
+}
+function registerCiteCommand(program) {
+  program.command("cite").description("Generate formatted citations for references").argument("<id-or-uuid...>", "Citation keys or UUIDs to cite").option("--uuid", "Treat arguments as UUIDs instead of IDs").option("--style <style>", "CSL style name").option("--csl-file <path>", "Path to custom CSL file").option("--locale <locale>", "Locale code (e.g., en-US, ja-JP)").option("--format <format>", "Output format: text|html|rtf").option("--in-text", "Generate in-text citations instead of bibliography entries").action(async (identifiers, options) => {
+    await handleCiteAction(identifiers, options, program);
+  });
+}
 function registerServerCommand(program) {
   const serverCmd = program.command("server").description("Manage HTTP server for library access");
   serverCmd.command("start").description("Start HTTP server").option("--port <port>", "Specify port number").option("-d, --daemon", "Run in background").action(async (options) => {
@@ -964,6 +1523,119 @@ Library: ${status.library}
     }
   });
 }
+function isValidFilePath(value) {
+  return typeof value === "string" && value !== "" && value !== "true";
+}
+function parseFulltextAttachTypeAndPath(filePathArg, options) {
+  if (options.pdf) {
+    return { type: "pdf", filePath: isValidFilePath(options.pdf) ? options.pdf : filePathArg };
+  }
+  if (options.markdown) {
+    return {
+      type: "markdown",
+      filePath: isValidFilePath(options.markdown) ? options.markdown : filePathArg
+    };
+  }
+  return { type: void 0, filePath: filePathArg };
+}
+async function handleFulltextAttachAction(identifier, filePathArg, options, program) {
+  try {
+    const globalOpts = program.opts();
+    const config = await loadConfigWithOverrides({ ...globalOpts, ...options });
+    const context = await createExecutionContext(config, Library.load);
+    const { type, filePath } = parseFulltextAttachTypeAndPath(filePathArg, options);
+    const stdinContent = !filePath && type ? await readStdinBuffer() : void 0;
+    const attachOptions = {
+      identifier,
+      fulltextDirectory: config.fulltext.directory,
+      ...filePath && { filePath },
+      ...type && { type },
+      ...options.move && { move: options.move },
+      ...options.force && { force: options.force },
+      ...options.uuid && { byUuid: options.uuid },
+      ...stdinContent && { stdinContent }
+    };
+    const result = await executeFulltextAttach(attachOptions, context);
+    const output = formatFulltextAttachOutput(result);
+    process.stderr.write(`${output}
+`);
+    process.exit(getFulltextExitCode(result));
+  } catch (error) {
+    process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
+`);
+    process.exit(4);
+  }
+}
+async function handleFulltextGetAction(identifier, options, program) {
+  try {
+    const globalOpts = program.opts();
+    const config = await loadConfigWithOverrides({ ...globalOpts, ...options });
+    const context = await createExecutionContext(config, Library.load);
+    const getOptions = {
+      identifier,
+      fulltextDirectory: config.fulltext.directory,
+      ...options.pdf && { type: "pdf" },
+      ...options.markdown && { type: "markdown" },
+      ...options.stdout && { stdout: options.stdout },
+      ...options.uuid && { byUuid: options.uuid }
+    };
+    const result = await executeFulltextGet(getOptions, context);
+    if (result.success && result.content && options.stdout) {
+      process.stdout.write(result.content);
+    } else {
+      const output = formatFulltextGetOutput(result);
+      if (result.success) {
+        process.stdout.write(`${output}
+`);
+      } else {
+        process.stderr.write(`${output}
+`);
+      }
+    }
+    process.exit(getFulltextExitCode(result));
+  } catch (error) {
+    process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
+`);
+    process.exit(4);
+  }
+}
+async function handleFulltextDetachAction(identifier, options, program) {
+  try {
+    const globalOpts = program.opts();
+    const config = await loadConfigWithOverrides({ ...globalOpts, ...options });
+    const context = await createExecutionContext(config, Library.load);
+    const detachOptions = {
+      identifier,
+      fulltextDirectory: config.fulltext.directory,
+      ...options.pdf && { type: "pdf" },
+      ...options.markdown && { type: "markdown" },
+      ...options.delete && { delete: options.delete },
+      ...options.force && { force: options.force },
+      ...options.uuid && { byUuid: options.uuid }
+    };
+    const result = await executeFulltextDetach(detachOptions, context);
+    const output = formatFulltextDetachOutput(result);
+    process.stderr.write(`${output}
+`);
+    process.exit(getFulltextExitCode(result));
+  } catch (error) {
+    process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}
+`);
+    process.exit(4);
+  }
+}
+function registerFulltextCommand(program) {
+  const fulltextCmd = program.command("fulltext").description("Manage full-text files attached to references");
+  fulltextCmd.command("attach").description("Attach a full-text file to a reference").argument("<identifier>", "Citation key or UUID").argument("[file-path]", "Path to the file to attach").option("--pdf [path]", "Attach as PDF (path optional if provided as argument)").option("--markdown [path]", "Attach as Markdown (path optional if provided as argument)").option("--move", "Move file instead of copy").option("-f, --force", "Overwrite existing attachment").option("--uuid", "Interpret identifier as UUID").action(async (identifier, filePath, options) => {
+    await handleFulltextAttachAction(identifier, filePath, options, program);
+  });
+  fulltextCmd.command("get").description("Get full-text file path or content").argument("<identifier>", "Citation key or UUID").option("--pdf", "Get PDF file only").option("--markdown", "Get Markdown file only").option("--stdout", "Output file content to stdout").option("--uuid", "Interpret identifier as UUID").action(async (identifier, options) => {
+    await handleFulltextGetAction(identifier, options, program);
+  });
+  fulltextCmd.command("detach").description("Detach full-text file from a reference").argument("<identifier>", "Citation key or UUID").option("--pdf", "Detach PDF only").option("--markdown", "Detach Markdown only").option("--delete", "Also delete the file from disk").option("-f, --force", "Skip confirmation for delete").option("--uuid", "Interpret identifier as UUID").action(async (identifier, options) => {
+    await handleFulltextDetachAction(identifier, options, program);
+  });
+}
 async function main(argv) {
   const program = createProgram();
   process.on("SIGINT", () => {