@ncukondo/reference-manager 0.5.2 → 0.6.0

package/dist/cli.js

@@ -1,19 +1,19 @@
 import { Command } from "commander";
 import { ZodOptional as ZodOptional$2, z } from "zod";
-import { L as Library, F as FileWatcher } from "./chunks/file-watcher-Dqkw6R7-.js";
+import { p as pickDefined, q as sortOrderSchema, r as paginationOptionsSchema, L as Library, F as FileWatcher, u as sortFieldSchema, v as searchSortFieldSchema } from "./chunks/file-watcher-Cwfnnw92.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 { join, extname } from "node:path";
 import { mkdir, unlink, rename, copyFile, rm, readFile } from "node:fs/promises";
-import { u as updateReference, g as getDefaultExportFromCjs, B as BUILTIN_STYLES, a as addReferences, c as citeReferences, l as listReferences, r as removeReference, s as searchReferences, b as startServerWithFileWatcher } from "./chunks/index-D4Q13N-R.js";
+import { u as updateReference, B as BUILTIN_STYLES, s as startServerWithFileWatcher } from "./chunks/index-CQO8hLYm.js";
 import process$1, { stdin, stdout } from "node:process";
-import { l as loadConfig } from "./chunks/loader-DuzyKV70.js";
+import { l as loadConfig } from "./chunks/loader-B_ZLxCQW.js";
 import { spawn } from "node:child_process";
 import { serve } from "@hono/node-server";
 const name = "@ncukondo/reference-manager";
-const version$1 = "0.5.2";
+const version$1 = "0.6.0";
 const description$1 = "A local reference management tool using CSL-JSON as the single source of truth";
 const packageJson = {
   name,
@@ -163,7 +163,7 @@ async function validateOptions$2(options) {
 function buildCiteOptions(options) {
   return {
     identifiers: options.identifiers,
-    ...options.uuid !== void 0 && { byUuid: options.uuid },
+    ...options.uuid && { idType: "uuid" },
     ...options.style !== void 0 && { style: options.style },
     ...options.cslFile !== void 0 && { cslFile: options.cslFile },
     ...options.locale !== void 0 && { locale: options.locale },
@@ -451,11 +451,11 @@ async function fulltextAttach(library, options) {
     type: explicitType,
     move,
     force,
-    byUuid = false,
+    idType = "id",
     fulltextDirectory,
     stdinContent
   } = options;
-  const item = await library.find(identifier, { byUuid });
+  const item = await library.find(identifier, { idType });
   if (!item) {
     return { success: false, error: `Reference '${identifier}' not found` };
   }
@@ -482,7 +482,7 @@ async function fulltextAttach(library, options) {
       updates: {
         custom: { fulltext: newFulltext }
       },
-      byUuid
+      idType
     });
     await cleanupTempDir(tempDir);
     return {
@@ -528,8 +528,8 @@ function getFilePaths(manager, item, types2, identifier) {
   return { success: true, paths };
 }
 async function fulltextGet(library, options) {
-  const { identifier, type: type2, stdout: stdout2, byUuid = false, fulltextDirectory } = options;
-  const item = await library.find(identifier, { byUuid });
+  const { identifier, type: type2, stdout: stdout2, idType = "id", fulltextDirectory } = options;
+  const item = await library.find(identifier, { idType });
   if (!item) {
     return { success: false, error: `Reference '${identifier}' not found` };
   }
@@ -573,8 +573,8 @@ function handleDetachError(error) {
   throw error;
 }
 async function fulltextDetach(library, options) {
-  const { identifier, type: type2, delete: deleteFile, byUuid = false, fulltextDirectory } = options;
-  const item = await library.find(identifier, { byUuid });
+  const { identifier, type: type2, delete: deleteFile, idType = "id", fulltextDirectory } = options;
+  const item = await library.find(identifier, { idType });
   if (!item) {
     return { success: false, error: `Reference '${identifier}' not found` };
   }
@@ -596,7 +596,7 @@ async function fulltextDetach(library, options) {
       updates: {
         custom: { fulltext: updatedFulltext }
       },
-      byUuid
+      idType
     });
     const resultData = { success: true, detached };
     if (deleted.length > 0) {
@@ -614,7 +614,7 @@ async function executeFulltextAttach(options, context) {
     type: options.type,
     move: options.move,
     force: options.force,
-    byUuid: options.byUuid,
+    idType: options.idType,
     fulltextDirectory: options.fulltextDirectory,
     stdinContent: options.stdinContent
   };
@@ -625,7 +625,7 @@ async function executeFulltextGet(options, context) {
     identifier: options.identifier,
     type: options.type,
     stdout: options.stdout,
-    byUuid: options.byUuid,
+    idType: options.idType,
     fulltextDirectory: options.fulltextDirectory
   };
   return fulltextGet(context.library, operationOptions);
@@ -635,7 +635,7 @@ async function executeFulltextDetach(options, context) {
     identifier: options.identifier,
     type: options.type,
     delete: options.delete,
-    byUuid: options.byUuid,
+    idType: options.idType,
     fulltextDirectory: options.fulltextDirectory
   };
   return fulltextDetach(context.library, operationOptions);
@@ -689,6 +689,40 @@ function formatFulltextDetachOutput(result) {
 function getFulltextExitCode(result) {
   return result.success ? 0 : 1;
 }
+const SORT_ALIASES = {
+  pub: "published",
+  mod: "updated",
+  add: "created",
+  rel: "relevance"
+};
+const VALID_SORT_FIELDS = /* @__PURE__ */ new Set([
+  "created",
+  "updated",
+  "published",
+  "author",
+  "title",
+  "relevance"
+]);
+function resolveSortAlias(alias) {
+  if (VALID_SORT_FIELDS.has(alias)) {
+    return alias;
+  }
+  const resolved = SORT_ALIASES[alias];
+  if (resolved) {
+    return resolved;
+  }
+  throw new Error(`Unknown sort field: ${alias}`);
+}
+const VALID_LIST_SORT_FIELDS = /* @__PURE__ */ new Set([
+  "created",
+  "updated",
+  "published",
+  "author",
+  "title",
+  "add",
+  "mod",
+  "pub"
+]);
 function getListFormat(options) {
   if (options.json) return "json";
   if (options.idsOnly) return "ids-only";
@@ -705,17 +739,58 @@ function validateOptions$1(options) {
       "Multiple output formats specified. Only one of --json, --ids-only, --uuid, --bibtex can be used."
     );
   }
+  if (options.sort !== void 0) {
+    const sortStr = String(options.sort);
+    if (!VALID_LIST_SORT_FIELDS.has(sortStr)) {
+      throw new Error(`Invalid sort field: ${sortStr}`);
+    }
+  }
+  if (options.order !== void 0) {
+    const result = sortOrderSchema.safeParse(options.order);
+    if (!result.success) {
+      throw new Error(`Invalid sort order: ${options.order}`);
+    }
+  }
+  const paginationResult = paginationOptionsSchema.safeParse({
+    limit: options.limit,
+    offset: options.offset
+  });
+  if (!paginationResult.success) {
+    const issue2 = paginationResult.error.issues[0];
+    throw new Error(`Invalid pagination option: ${issue2?.message ?? "unknown error"}`);
+  }
 }
 async function executeList(options, context) {
   validateOptions$1(options);
   const format2 = getListFormat(options);
-  return context.library.list({ format: format2 });
+  const sort = options.sort ? resolveSortAlias(options.sort) : void 0;
+  return context.library.list({
+    format: format2,
+    ...sort !== void 0 && { sort },
+    ...pickDefined(options, ["order", "limit", "offset"])
+  });
 }
-function formatListOutput(result) {
+function formatListOutput(result, isJson = false) {
+  if (isJson) {
+    return JSON.stringify({
+      items: result.items,
+      total: result.total,
+      limit: result.limit,
+      offset: result.offset,
+      nextOffset: result.nextOffset
+    });
+  }
   if (result.items.length === 0) {
     return "";
   }
-  return result.items.join("\n");
+  const lines = [];
+  if (result.limit > 0 && result.total > 0) {
+    const start = result.offset + 1;
+    const end = result.offset + result.items.length;
+    lines.push(`# Showing ${start}-${end} of ${result.total} references`);
+  }
+  lines.push(...result.items);
+  return lines.join("\n");
 }
 var util$1;
 (function(util2) {
@@ -12494,6 +12569,9 @@ function mergeCapabilities(base, additional) {
   }
   return result;
 }
+function getDefaultExportFromCjs(x) {
+  return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, "default") ? x["default"] : x;
+}
 var ajv = { exports: {} };
 var core$1 = {};
 var validate = {};
@@ -20856,12 +20934,54 @@ class StdioServerTransport {
     });
   }
 }
+class OperationsLibrary {
+  constructor(library) {
+    this.library = library;
+  }
+  // ILibrary delegation
+  find(identifier, options) {
+    return this.library.find(identifier, options);
+  }
+  getAll() {
+    return this.library.getAll();
+  }
+  add(item) {
+    return this.library.add(item);
+  }
+  update(idOrUuid, updates, options) {
+    return this.library.update(idOrUuid, updates, options);
+  }
+  remove(identifier, options) {
+    return this.library.remove(identifier, options);
+  }
+  save() {
+    return this.library.save();
+  }
+  // High-level operations
+  async search(options) {
+    const { searchReferences } = await import("./chunks/index-CQO8hLYm.js").then((n) => n.d);
+    return searchReferences(this.library, options);
+  }
+  async list(options) {
+    const { listReferences } = await import("./chunks/index-CQO8hLYm.js").then((n) => n.l);
+    return listReferences(this.library, options ?? {});
+  }
+  async cite(options) {
+    const { citeReferences } = await import("./chunks/index-CQO8hLYm.js").then((n) => n.b);
+    return citeReferences(this.library, options);
+  }
+  async import(inputs, options) {
+    const { addReferences } = await import("./chunks/index-CQO8hLYm.js").then((n) => n.a);
+    return addReferences(inputs, this.library, options ?? {});
+  }
+}
 async function createMcpContext(options) {
   const config2 = await loadConfig({
     userConfigPath: options.configPath
   });
   const libraryPath = options.libraryPath ?? config2.library;
   const library = await Library.load(libraryPath);
+  const libraryOperations = new OperationsLibrary(library);
   const fileWatcher = new FileWatcher(libraryPath, {
     debounceMs: config2.watch.debounceMs,
     maxRetries: config2.watch.maxRetries,
@@ -20877,13 +20997,13 @@ async function createMcpContext(options) {
     fileWatcher.close();
   };
   return {
-    library,
+    libraryOperations,
     config: config2,
     fileWatcher,
     dispose
   };
 }
-function registerReferencesResource(server, getLibrary) {
+function registerReferencesResource(server, getLibraryOperations) {
   server.registerResource(
     "references",
     "library://references",
@@ -20892,8 +21012,8 @@ function registerReferencesResource(server, getLibrary) {
       mimeType: "application/json"
     },
     async (uri2) => {
-      const library = getLibrary();
-      const items2 = await library.getAll();
+      const libraryOps = getLibraryOperations();
+      const items2 = await libraryOps.getAll();
       return {
         contents: [
           {
@@ -20906,11 +21026,11 @@ function registerReferencesResource(server, getLibrary) {
     }
   );
 }
-function registerReferenceResource(server, getLibrary) {
+function registerReferenceResource(server, getLibraryOperations) {
   const template = new ResourceTemplate("library://reference/{id}", {
     list: async () => {
-      const library = getLibrary();
-      const items2 = await library.getAll();
+      const libraryOps = getLibraryOperations();
+      const items2 = await libraryOps.getAll();
       return {
         resources: items2.map((item) => ({
           uri: `library://reference/${item.id}`,
@@ -20927,9 +21047,9 @@ function registerReferenceResource(server, getLibrary) {
       mimeType: "application/json"
     },
     async (uri2, variables) => {
-      const library = getLibrary();
+      const libraryOps = getLibraryOperations();
       const id2 = variables.id;
-      const item = await library.find(id2);
+      const item = await libraryOps.find(id2);
       if (!item) {
         throw new Error(`Reference not found: ${id2}`);
       }
@@ -20970,9 +21090,9 @@ function registerStylesResource(server) {
     }
   );
 }
-function registerAllResources(server, getLibrary) {
-  registerReferencesResource(server, getLibrary);
-  registerReferenceResource(server, getLibrary);
+function registerAllResources(server, getLibraryOperations) {
+  registerReferencesResource(server, getLibraryOperations);
+  registerReferenceResource(server, getLibraryOperations);
   registerStylesResource(server);
 }
 function formatAddResult(result) {
@@ -21001,7 +21121,7 @@ function formatAddResult(result) {
   }
   return lines.join("\n");
 }
-function registerAddTool(server, getLibrary) {
+function registerAddTool(server, getLibraryOperations) {
   server.registerTool(
     "add",
     {
@@ -21011,10 +21131,10 @@ function registerAddTool(server, getLibrary) {
       }
     },
     async (args) => {
-      const library = getLibrary();
+      const libraryOps = getLibraryOperations();
       const inputs = Array.isArray(args.input) ? args.input : [args.input];
       const stdinContent = inputs.join("\n");
-      const result = await addReferences([], library, { stdinContent });
+      const result = await libraryOps.import([], { stdinContent });
       return {
         content: [
           {
@@ -21026,7 +21146,7 @@ function registerAddTool(server, getLibrary) {
     }
   );
 }
-function registerCiteTool(server, getLibrary) {
+function registerCiteTool(server, getLibraryOperations) {
   server.registerTool(
     "cite",
     {
@@ -21038,8 +21158,8 @@ function registerCiteTool(server, getLibrary) {
       }
     },
     async (args) => {
-      const library = getLibrary();
-      const result = await citeReferences(library, {
+      const libraryOps = getLibraryOperations();
+      const result = await libraryOps.cite({
         identifiers: args.ids,
         style: args.style ?? "apa",
         format: args.format ?? "text"
@@ -21053,7 +21173,7 @@ function registerCiteTool(server, getLibrary) {
     }
   );
 }
-function registerFulltextAttachTool(server, getLibrary, getConfig) {
+function registerFulltextAttachTool(server, getLibraryOperations, getConfig) {
   server.registerTool(
     "fulltext_attach",
     {
@@ -21064,9 +21184,9 @@ function registerFulltextAttachTool(server, getLibrary, getConfig) {
       }
     },
     async (args) => {
-      const library = getLibrary();
+      const libraryOps = getLibraryOperations();
       const config2 = getConfig();
-      const result = await fulltextAttach(library, {
+      const result = await fulltextAttach(libraryOps, {
         identifier: args.id,
         filePath: args.path,
         force: true,
@@ -21090,7 +21210,7 @@ function registerFulltextAttachTool(server, getLibrary, getConfig) {
     }
   );
 }
-function registerFulltextGetTool(server, getLibrary, getConfig) {
+function registerFulltextGetTool(server, getLibraryOperations, getConfig) {
   server.registerTool(
     "fulltext_get",
     {
@@ -21100,9 +21220,9 @@ function registerFulltextGetTool(server, getLibrary, getConfig) {
       }
     },
     async (args) => {
-      const library = getLibrary();
+      const libraryOps = getLibraryOperations();
       const config2 = getConfig();
-      const pathResult = await fulltextGet(library, {
+      const pathResult = await fulltextGet(libraryOps, {
         identifier: args.id,
         fulltextDirectory: config2.fulltext.directory
       });
@@ -21114,7 +21234,7 @@ function registerFulltextGetTool(server, getLibrary, getConfig) {
       }
       const responses = [];
       if (pathResult.paths?.markdown) {
-        const contentResult = await fulltextGet(library, {
+        const contentResult = await fulltextGet(libraryOps, {
           identifier: args.id,
           type: "markdown",
           stdout: true,
@@ -21143,7 +21263,7 @@ function registerFulltextGetTool(server, getLibrary, getConfig) {
     }
   );
 }
-function registerFulltextDetachTool(server, getLibrary, getConfig) {
+function registerFulltextDetachTool(server, getLibraryOperations, getConfig) {
   server.registerTool(
     "fulltext_detach",
     {
@@ -21153,9 +21273,9 @@ function registerFulltextDetachTool(server, getLibrary, getConfig) {
       }
     },
     async (args) => {
-      const library = getLibrary();
+      const libraryOps = getLibraryOperations();
       const config2 = getConfig();
-      const result = await fulltextDetach(library, {
+      const result = await fulltextDetach(libraryOps, {
         identifier: args.id,
         fulltextDirectory: config2.fulltext.directory
       });
@@ -21177,30 +21297,46 @@ function registerFulltextDetachTool(server, getLibrary, getConfig) {
     }
   );
 }
-function registerListTool(server, getLibrary) {
+function registerListTool(server, getLibraryOperations, getConfig) {
   server.registerTool(
     "list",
     {
-      description: "List all references in the library. Supports different output formats.",
+      description: "List references in the library. Supports different output formats, sorting, and pagination.",
       inputSchema: {
-        format: z.enum(["json", "bibtex", "pretty"]).optional().describe("Output format: json, bibtex, or pretty (default: pretty)")
+        format: z.enum(["json", "bibtex", "pretty"]).optional().describe("Output format: json, bibtex, or pretty (default: pretty)"),
+        sort: sortFieldSchema.optional().describe("Sort by field: created, updated, published, author, title (default: updated)"),
+        order: sortOrderSchema.optional().describe("Sort order: asc or desc (default: desc)"),
+        limit: z.number().int().min(0).optional().describe("Maximum number of results (0 = no limit)"),
+        offset: z.number().int().min(0).optional().describe("Number of results to skip (default: 0)")
       }
     },
     async (args) => {
-      const library = getLibrary();
-      const result = await listReferences(library, {
-        format: args.format ?? "pretty"
+      const libraryOps = getLibraryOperations();
+      const config2 = getConfig();
+      const limit2 = args.limit ?? config2.mcp.defaultLimit;
+      const result = await libraryOps.list({
+        format: args.format ?? "pretty",
+        limit: limit2,
+        ...pickDefined(args, ["sort", "order", "offset"])
       });
       return {
-        content: result.items.map((item) => ({
-          type: "text",
-          text: item
-        }))
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              total: result.total,
+              limit: result.limit,
+              offset: result.offset,
+              nextOffset: result.nextOffset,
+              items: result.items
+            })
+          }
+        ]
       };
     }
   );
 }
-function registerRemoveTool(server, getLibrary) {
+function registerRemoveTool(server, getLibraryOperations) {
   server.registerTool(
     "remove",
     {
@@ -21221,8 +21357,8 @@ function registerRemoveTool(server, getLibrary) {
           ]
         };
       }
-      const library = getLibrary();
-      const result = await removeReference(library, { identifier: args.id });
+      const libraryOps = getLibraryOperations();
+      const result = await libraryOps.remove(args.id);
       if (!result.removed) {
         return {
           content: [
@@ -21246,39 +21382,57 @@ Title: ${title2}`
     }
   );
 }
-function registerSearchTool(server, getLibrary) {
+function registerSearchTool(server, getLibraryOperations, getConfig) {
   server.registerTool(
     "search",
     {
-      description: "Search references in the library. Supports query syntax: author:name, year:YYYY, title:text, type:article-journal, tag:name, or free text for full-text search.",
+      description: "Search references in the library. Supports query syntax: author:name, year:YYYY, title:text, type:article-journal, tag:name, or free text for full-text search. Supports sorting and pagination.",
       inputSchema: {
-        query: z.string().describe("Search query string")
+        query: z.string().describe("Search query string"),
+        sort: searchSortFieldSchema.optional().describe(
+          "Sort by field: created, updated, published, author, title, relevance (default: updated)"
+        ),
+        order: sortOrderSchema.optional().describe("Sort order: asc or desc (default: desc)"),
+        limit: z.number().int().min(0).optional().describe("Maximum number of results (0 = no limit)"),
+        offset: z.number().int().min(0).optional().describe("Number of results to skip (default: 0)")
       }
     },
     async (args) => {
-      const library = getLibrary();
-      const result = await searchReferences(library, {
+      const libraryOps = getLibraryOperations();
+      const config2 = getConfig();
+      const limit2 = args.limit ?? config2.mcp.defaultLimit;
+      const result = await libraryOps.search({
         query: args.query,
-        format: "pretty"
+        format: "pretty",
+        limit: limit2,
+        ...pickDefined(args, ["sort", "order", "offset"])
       });
       return {
-        content: result.items.map((item) => ({
-          type: "text",
-          text: item
-        }))
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              total: result.total,
+              limit: result.limit,
+              offset: result.offset,
+              nextOffset: result.nextOffset,
+              items: result.items
+            })
+          }
+        ]
       };
     }
   );
 }
-function registerAllTools(server, getLibrary, getConfig) {
-  registerSearchTool(server, getLibrary);
-  registerListTool(server, getLibrary);
-  registerCiteTool(server, getLibrary);
-  registerAddTool(server, getLibrary);
-  registerRemoveTool(server, getLibrary);
-  registerFulltextAttachTool(server, getLibrary, getConfig);
-  registerFulltextGetTool(server, getLibrary, getConfig);
-  registerFulltextDetachTool(server, getLibrary, getConfig);
+function registerAllTools(server, getLibraryOperations, getConfig) {
+  registerSearchTool(server, getLibraryOperations, getConfig);
+  registerListTool(server, getLibraryOperations, getConfig);
+  registerCiteTool(server, getLibraryOperations);
+  registerAddTool(server, getLibraryOperations);
+  registerRemoveTool(server, getLibraryOperations);
+  registerFulltextAttachTool(server, getLibraryOperations, getConfig);
+  registerFulltextGetTool(server, getLibraryOperations, getConfig);
+  registerFulltextDetachTool(server, getLibraryOperations, getConfig);
 }
 async function createMcpServer(options) {
   const serverInfo = {
@@ -21293,10 +21447,10 @@ async function createMcpServer(options) {
   }
   const context = await createMcpContext(contextOptions);
   const server = new McpServer(serverInfo);
-  const getLibrary = () => context.library;
+  const getLibraryOperations = () => context.libraryOperations;
   const getConfig = () => context.config;
-  registerAllTools(server, getLibrary, getConfig);
-  registerAllResources(server, getLibrary);
+  registerAllTools(server, getLibraryOperations, getConfig);
+  registerAllResources(server, getLibraryOperations);
   const transport = new StdioServerTransport(
     options.stdin ?? process.stdin,
     options.stdout ?? process.stdout
@@ -21330,8 +21484,8 @@ async function mcpStart(options) {
   return result;
 }
 async function executeRemove(options, context) {
-  const { identifier, byUuid = false } = options;
-  return context.library.remove(identifier, { byUuid });
+  const { identifier, idType = "id" } = options;
+  return context.library.remove(identifier, { idType });
 }
 function formatRemoveOutput(result, identifier) {
   if (!result.removed) {
@@ -21378,6 +21532,18 @@ async function deleteFulltextFiles(item, fulltextDirectory) {
     }
   }
 }
+const VALID_SEARCH_SORT_FIELDS = /* @__PURE__ */ new Set([
+  "created",
+  "updated",
+  "published",
+  "author",
+  "title",
+  "relevance",
+  "add",
+  "mod",
+  "pub",
+  "rel"
+]);
 function getSearchFormat(options) {
   if (options.json) return "json";
   if (options.idsOnly) return "ids-only";
@@ -21394,17 +21560,59 @@ function validateOptions(options) {
       "Multiple output formats specified. Only one of --json, --ids-only, --uuid, --bibtex can be used."
     );
   }
+  if (options.sort !== void 0) {
+    const sortStr = String(options.sort);
+    if (!VALID_SEARCH_SORT_FIELDS.has(sortStr)) {
+      throw new Error(`Invalid sort field: ${sortStr}`);
+    }
+  }
+  if (options.order !== void 0) {
+    const result = sortOrderSchema.safeParse(options.order);
+    if (!result.success) {
+      throw new Error(`Invalid sort order: ${options.order}`);
+    }
+  }
+  const paginationResult = paginationOptionsSchema.safeParse({
+    limit: options.limit,
+    offset: options.offset
+  });
+  if (!paginationResult.success) {
+    const issue2 = paginationResult.error.issues[0];
+    throw new Error(`Invalid pagination option: ${issue2?.message ?? "unknown error"}`);
+  }
 }
 async function executeSearch(options, context) {
   validateOptions(options);
   const format2 = getSearchFormat(options);
-  return context.library.search({ query: options.query, format: format2 });
+  const sort = options.sort ? resolveSortAlias(options.sort) : void 0;
+  return context.library.search({
+    query: options.query,
+    format: format2,
+    ...sort !== void 0 && { sort },
+    ...pickDefined(options, ["order", "limit", "offset"])
+  });
 }
-function formatSearchOutput(result) {
+function formatSearchOutput(result, isJson = false) {
+  if (isJson) {
+    return JSON.stringify({
+      items: result.items,
+      total: result.total,
+      limit: result.limit,
+      offset: result.offset,
+      nextOffset: result.nextOffset
+    });
+  }
   if (result.items.length === 0) {
     return "";
   }
-  return result.items.join("\n");
+  const lines = [];
+  if (result.limit > 0 && result.total > 0) {
+    const start = result.offset + 1;
+    const end = result.offset + result.items.length;
+    lines.push(`# Showing ${start}-${end} of ${result.total} references`);
+  }
+  lines.push(...result.items);
+  return lines.join("\n");
 }
 async function serverStart(options) {
   const existingStatus = await serverStatus(options.portfilePath);
@@ -21491,8 +21699,8 @@ async function serverStatus(portfilePath) {
   return result;
 }
 async function executeUpdate(options, context) {
-  const { identifier, updates, byUuid = false } = options;
-  return context.library.update(identifier, updates, { byUuid });
+  const { identifier, updates, idType = "id" } = options;
+  return context.library.update(identifier, updates, { idType });
 }
 function formatUpdateOutput(result, identifier) {
   if (!result.updated) {
@@ -21513,47 +21721,6 @@ function formatUpdateOutput(result, identifier) {
   }
   return parts.join("\n");
 }
-class OperationsLibrary {
-  constructor(library) {
-    this.library = library;
-  }
-  // ILibrary delegation
-  find(identifier, options) {
-    return this.library.find(identifier, options);
-  }
-  getAll() {
-    return this.library.getAll();
-  }
-  add(item) {
-    return this.library.add(item);
-  }
-  update(idOrUuid, updates, options) {
-    return this.library.update(idOrUuid, updates, options);
-  }
-  remove(identifier, options) {
-    return this.library.remove(identifier, options);
-  }
-  save() {
-    return this.library.save();
-  }
-  // High-level operations
-  async search(options) {
-    const { searchReferences: searchReferences2 } = await import("./chunks/index-D4Q13N-R.js").then((n) => n.i);
-    return searchReferences2(this.library, options);
-  }
-  async list(options) {
-    const { listReferences: listReferences2 } = await import("./chunks/index-D4Q13N-R.js").then((n) => n.h);
-    return listReferences2(this.library, options ?? {});
-  }
-  async cite(options) {
-    const { citeReferences: citeReferences2 } = await import("./chunks/index-D4Q13N-R.js").then((n) => n.f);
-    return citeReferences2(this.library, options);
-  }
-  async import(inputs, options) {
-    const { addReferences: addReferences2 } = await import("./chunks/index-D4Q13N-R.js").then((n) => n.e);
-    return addReferences2(inputs, this.library, options ?? {});
-  }
-}
 class ServerClient {
   constructor(baseUrl) {
     this.baseUrl = baseUrl;
@@ -21576,12 +21743,12 @@ class ServerClient {
   /**
    * Find reference by citation ID or UUID.
    * @param identifier - Citation ID or UUID
-   * @param options - Find options (byUuid to use UUID lookup)
+   * @param options - Find options (idType to specify identifier type)
    * @returns CSL item or undefined if not found
    */
   async find(identifier, options = {}) {
-    const { byUuid = false } = options;
-    const url = byUuid ? `${this.baseUrl}/api/references/uuid/${encodeURIComponent(identifier)}` : `${this.baseUrl}/api/references/id/${encodeURIComponent(identifier)}`;
+    const { idType = "id" } = options;
+    const url = idType === "uuid" ? `${this.baseUrl}/api/references/uuid/${encodeURIComponent(identifier)}` : `${this.baseUrl}/api/references/id/${encodeURIComponent(identifier)}`;
     const response = await fetch(url);
     if (response.status === 404) {
       return void 0;
@@ -21615,12 +21782,12 @@ class ServerClient {
    * Update reference by citation ID or UUID.
    * @param identifier - Citation ID or UUID
    * @param updates - Partial CSL item with fields to update
-   * @param options - Update options (byUuid to use UUID lookup, onIdCollision for collision handling)
+   * @param options - Update options (idType to specify identifier type, onIdCollision for collision handling)
    * @returns Update result with updated item, success status, and any ID changes
    */
   async update(identifier, updates, options) {
-    const { byUuid = false, onIdCollision } = options ?? {};
-    const url = byUuid ? `${this.baseUrl}/api/references/uuid/${encodeURIComponent(identifier)}` : `${this.baseUrl}/api/references/id/${encodeURIComponent(identifier)}`;
+    const { idType = "id", onIdCollision } = options ?? {};
+    const url = idType === "uuid" ? `${this.baseUrl}/api/references/uuid/${encodeURIComponent(identifier)}` : `${this.baseUrl}/api/references/id/${encodeURIComponent(identifier)}`;
     const response = await fetch(url, {
       method: "PUT",
       headers: { "Content-Type": "application/json" },
@@ -21640,12 +21807,12 @@ class ServerClient {
   /**
    * 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)
+   * @param options - Remove options (idType to specify identifier type)
    * @returns Remove result with removed status and removedItem
    */
   async remove(identifier, options = {}) {
-    const { byUuid = false } = options;
-    const url = byUuid ? `${this.baseUrl}/api/references/uuid/${encodeURIComponent(identifier)}` : `${this.baseUrl}/api/references/id/${encodeURIComponent(identifier)}`;
+    const { idType = "id" } = options;
+    const url = idType === "uuid" ? `${this.baseUrl}/api/references/uuid/${encodeURIComponent(identifier)}` : `${this.baseUrl}/api/references/id/${encodeURIComponent(identifier)}`;
     const response = await fetch(url, {
       method: "DELETE"
     });
@@ -21783,6 +21950,199 @@ async function waitForPortfile(timeoutMs) {
   }
   throw new Error(`Server failed to start: portfile not created within ${timeoutMs}ms`);
 }
+const SEARCH_SORT_FIELDS = searchSortFieldSchema.options;
+const SORT_ORDERS = sortOrderSchema.options;
+const CITATION_FORMATS = ["text", "html", "rtf"];
+const LOG_LEVELS = ["silent", "info", "debug"];
+const OPTION_VALUES = {
+  "--sort": SEARCH_SORT_FIELDS,
+  // search includes 'relevance'
+  "--order": SORT_ORDERS,
+  "--format": CITATION_FORMATS,
+  "--style": BUILTIN_STYLES,
+  "--log-level": LOG_LEVELS
+};
+const ID_COMPLETION_COMMANDS = /* @__PURE__ */ new Set(["cite", "remove", "update"]);
+const ID_COMPLETION_FULLTEXT_SUBCOMMANDS = /* @__PURE__ */ new Set(["attach", "get", "detach"]);
+function toCompletionItems(values) {
+  return values.map((name2) => ({ name: name2 }));
+}
+function extractSubcommands(program) {
+  return program.commands.map((cmd) => ({
+    name: cmd.name(),
+    description: cmd.description()
+  }));
+}
+function extractOptions(cmd) {
+  const options = [];
+  for (const opt of cmd.options) {
+    const longFlag = opt.long;
+    const shortFlag = opt.short;
+    const description2 = opt.description;
+    if (longFlag) {
+      options.push({ name: longFlag, description: description2 });
+    }
+    if (shortFlag) {
+      options.push({ name: shortFlag, description: description2 });
+    }
+  }
+  return options;
+}
+function extractGlobalOptions(program) {
+  const options = extractOptions(program);
+  options.push({ name: "--help", description: "display help for command" });
+  options.push({ name: "--version", description: "output the version number" });
+  return options;
+}
+function findSubcommand(program, name2) {
+  return program.commands.find((cmd) => cmd.name() === name2);
+}
+function getCompletions(env, program) {
+  const { line, prev, last } = env;
+  const words = line.trim().split(/\s+/);
+  const args = words.slice(1);
+  const subcommands = extractSubcommands(program);
+  const globalOptions = extractGlobalOptions(program);
+  if (args.length === 0) {
+    return subcommands;
+  }
+  const firstArg = args[0] ?? "";
+  if (prev?.startsWith("-")) {
+    const optionValues = OPTION_VALUES[prev];
+    if (optionValues) {
+      return toCompletionItems(optionValues);
+    }
+  }
+  if (last.startsWith("-")) {
+    const subCmd = findSubcommand(program, firstArg);
+    const commandOptions = subCmd ? extractOptions(subCmd) : [];
+    return [...commandOptions, ...globalOptions];
+  }
+  const parentCmd = findSubcommand(program, firstArg);
+  if (parentCmd && parentCmd.commands.length > 0) {
+    const nestedSubcommands = extractSubcommands(parentCmd);
+    if (args.length === 1 || args.length === 2 && !last.startsWith("-")) {
+      return nestedSubcommands;
+    }
+  }
+  if (args.length === 1) {
+    return subcommands.filter((cmd) => cmd.name.startsWith(last));
+  }
+  return subcommands;
+}
+function needsIdCompletion(env) {
+  const { line, prev } = env;
+  const words = line.trim().split(/\s+/);
+  const args = words.slice(1);
+  if (args.length === 0) {
+    return { needs: false };
+  }
+  const command = args[0] ?? "";
+  if (prev?.startsWith("-")) {
+    return { needs: false };
+  }
+  if (command === "fulltext" && args.length >= 2) {
+    const subcommand = args[1] ?? "";
+    if (ID_COMPLETION_FULLTEXT_SUBCOMMANDS.has(subcommand)) {
+      return { needs: true, command, subcommand };
+    }
+    return { needs: false };
+  }
+  if (ID_COMPLETION_COMMANDS.has(command)) {
+    return { needs: true, command };
+  }
+  return { needs: false };
+}
+const MAX_ID_COMPLETIONS = 100;
+async function getLibraryForCompletion() {
+  try {
+    const config2 = loadConfig();
+    const server = await getServerConnection(config2.library, config2);
+    if (server) {
+      return new ServerClient(server.baseUrl);
+    }
+    return await Library.load(config2.library);
+  } catch {
+    return void 0;
+  }
+}
+function truncateTitle(title2, maxLength = 40) {
+  if (!title2) return "";
+  if (title2.length <= maxLength) return title2;
+  return `${title2.slice(0, maxLength - 3)}...`;
+}
+async function getIdCompletions(library, prefix) {
+  try {
+    const items2 = await library.getAll();
+    const completions = [];
+    for (const item of items2) {
+      const id2 = item.id;
+      if (!id2) continue;
+      if (prefix && !id2.toLowerCase().startsWith(prefix.toLowerCase())) {
+        continue;
+      }
+      completions.push({
+        name: id2,
+        description: truncateTitle(item.title)
+      });
+      if (completions.length >= MAX_ID_COMPLETIONS) {
+        break;
+      }
+    }
+    return completions;
+  } catch {
+    return [];
+  }
+}
+async function installCompletion() {
+  const tabtab = await import("tabtab");
+  await tabtab.install({
+    name: "ref",
+    completer: "ref"
+  });
+}
+async function uninstallCompletion() {
+  const tabtab = await import("tabtab");
+  await tabtab.uninstall({
+    name: "ref"
+  });
+}
+async function handleCompletion(program) {
+  const tabtab = await import("tabtab");
+  const env = tabtab.parseEnv(process.env);
+  if (!env.complete) {
+    return;
+  }
+  if (env.last.startsWith("-")) {
+    const completions2 = getCompletions(env, program);
+    tabtab.log(completions2);
+    return;
+  }
+  const idContext = needsIdCompletion(env);
+  if (idContext.needs) {
+    const library = await getLibraryForCompletion();
+    if (library) {
+      const idCompletions = await getIdCompletions(library, env.last);
+      tabtab.log(idCompletions);
+      return;
+    }
+  }
+  const completions = getCompletions(env, program);
+  tabtab.log(completions);
+}
+function registerCompletionCommand(program) {
+  program.command("completion").description("Install or uninstall shell completion").argument("[action]", "Action to perform (install or uninstall)", "install").action(async (action) => {
+    if (action === "install") {
+      await installCompletion();
+    } else if (action === "uninstall") {
+      await uninstallCompletion();
+    } else {
+      console.error(`Unknown action: ${action}`);
+      console.error("Usage: ref completion [install|uninstall]");
+      process.exit(1);
+    }
+  });
+}
 async function createExecutionContext(config2, loadLibrary) {
   const server = await getServerConnection(config2.library, config2);
   if (server) {
@@ -21894,6 +22254,7 @@ function createProgram() {
   registerServerCommand(program);
   registerFulltextCommand(program);
   registerMcpCommand(program);
+  registerCompletionCommand(program);
   return program;
 }
 async function handleListAction(options, program) {
@@ -21902,7 +22263,7 @@ async function handleListAction(options, program) {
     const config2 = await loadConfigWithOverrides({ ...globalOpts, ...options });
     const context = await createExecutionContext(config2, Library.load);
     const result = await executeList(options, context);
-    const output = formatListOutput(result);
+    const output = formatListOutput(result, options.json ?? false);
     if (output) {
       process.stdout.write(`${output}
 `);
@@ -21915,7 +22276,7 @@ async function handleListAction(options, 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) => {
+  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").option("--sort <field>", "Sort by field: created|updated|published|author|title").option("--order <order>", "Sort order: asc|desc").option("-n, --limit <n>", "Maximum number of results", Number.parseInt).option("--offset <n>", "Number of results to skip", Number.parseInt).action(async (options) => {
     await handleListAction(options, program);
   });
 }
@@ -21925,7 +22286,7 @@ async function handleSearchAction(query, options, program) {
     const config2 = await loadConfigWithOverrides({ ...globalOpts, ...options });
     const context = await createExecutionContext(config2, Library.load);
     const result = await executeSearch({ ...options, query }, context);
-    const output = formatSearchOutput(result);
+    const output = formatSearchOutput(result, options.json ?? false);
     if (output) {
       process.stdout.write(`${output}
 `);
@@ -21938,7 +22299,7 @@ async function handleSearchAction(query, options, program) {
   }
 }
 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) => {
+  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").option("--sort <field>", "Sort by field: created|updated|published|author|title|relevance").option("--order <order>", "Sort order: asc|desc").option("-n, --limit <n>", "Maximum number of results", Number.parseInt).option("--offset <n>", "Number of results to skip", Number.parseInt).action(async (query, options) => {
     await handleSearchAction(query, options, program);
   });
 }
@@ -21987,12 +22348,16 @@ async function handleAddAction(inputs, options, program) {
   }
 }
 function registerAddCommand(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) => {
+  program.command("add").description("Add new reference(s) to the library").argument("[input...]", "File paths or identifiers (PMID/DOI/ISBN), or use stdin").option("-f, --force", "Skip duplicate detection").option(
+    "--format <format>",
+    "Explicit input format: json|bibtex|ris|pmid|doi|isbn|auto",
+    "auto"
+  ).option("--verbose", "Show detailed error information").action(async (inputs, options) => {
     await handleAddAction(inputs, options, program);
   });
 }
-async function findReferenceToRemove(identifier, byUuid, context) {
-  return context.library.find(identifier, { byUuid });
+async function findReferenceToRemove(identifier, useUuid, context) {
+  return context.library.find(identifier, { idType: useUuid ? "uuid" : "id" });
 }
 async function confirmRemoval(refToRemove, force, fulltextWarning) {
   if (force || !isTTY()) {
@@ -22060,8 +22425,8 @@ async function handleRemoveAction(identifier, options, program) {
     const removeOptions = {
       identifier
     };
-    if (options.uuid !== void 0) {
-      removeOptions.byUuid = options.uuid;
+    if (options.uuid) {
+      removeOptions.idType = "uuid";
     }
     const result = await executeRemove(removeOptions, context);
     const output = formatRemoveOutput(result, identifier);
@@ -22115,8 +22480,8 @@ async function handleUpdateAction(identifier, file, options, program) {
       identifier,
       updates: validatedUpdates
     };
-    if (options.uuid !== void 0) {
-      updateOptions.byUuid = options.uuid;
+    if (options.uuid) {
+      updateOptions.idType = "uuid";
     }
     const result = await executeUpdate(updateOptions, context);
     const output = formatUpdateOutput(result, identifier);
@@ -22296,7 +22661,7 @@ async function handleFulltextAttachAction(identifier, filePathArg, options, prog
       ...type2 && { type: type2 },
       ...options.move && { move: options.move },
       ...options.force && { force: options.force },
-      ...options.uuid && { byUuid: options.uuid },
+      ...options.uuid && { idType: "uuid" },
       ...stdinContent && { stdinContent }
     };
     const result = await executeFulltextAttach(attachOptions, context);
@@ -22321,7 +22686,7 @@ async function handleFulltextGetAction(identifier, options, program) {
       ...options.pdf && { type: "pdf" },
       ...options.markdown && { type: "markdown" },
       ...options.stdout && { stdout: options.stdout },
-      ...options.uuid && { byUuid: options.uuid }
+      ...options.uuid && { idType: "uuid" }
     };
     const result = await executeFulltextGet(getOptions, context);
     if (result.success && result.content && options.stdout) {
@@ -22355,7 +22720,7 @@ async function handleFulltextDetachAction(identifier, options, program) {
       ...options.markdown && { type: "markdown" },
       ...options.delete && { delete: options.delete },
       ...options.force && { force: options.force },
-      ...options.uuid && { byUuid: options.uuid }
+      ...options.uuid && { idType: "uuid" }
     };
     const result = await executeFulltextDetach(detachOptions, context);
     const output = formatFulltextDetachOutput(result);
@@ -22382,6 +22747,10 @@ function registerFulltextCommand(program) {
 }
 async function main(argv) {
   const program = createProgram();
+  if (process.env.COMP_LINE) {
+    await handleCompletion(program);
+    return;
+  }
   process.on("SIGINT", () => {
     process.exit(130);
   });