@ncukondo/reference-manager 0.5.3 → 0.7.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-CBAbblss.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-D7oyc-9z.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, 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-Bl_mOQRe.js";
+import { u as updateReference, B as BUILTIN_STYLES, s as startServerWithFileWatcher } from "./chunks/index-_7NEUoS7.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-BItrdVWG.js";
 import { spawn } from "node:child_process";
 import { serve } from "@hono/node-server";
 const name = "@ncukondo/reference-manager";
-const version$1 = "0.5.3";
+const version$1 = "0.7.0";
 const description$1 = "A local reference management tool using CSL-JSON as the single source of truth";
 const packageJson = {
   name,
@@ -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) {
@@ -20859,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-_7NEUoS7.js").then((n) => n.e);
+    return searchReferences(this.library, options);
+  }
+  async list(options) {
+    const { listReferences } = await import("./chunks/index-_7NEUoS7.js").then((n) => n.l);
+    return listReferences(this.library, options ?? {});
+  }
+  async cite(options) {
+    const { citeReferences } = await import("./chunks/index-_7NEUoS7.js").then((n) => n.d);
+    return citeReferences(this.library, options);
+  }
+  async import(inputs, options) {
+    const { addReferences } = await import("./chunks/index-_7NEUoS7.js").then((n) => n.b);
+    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,
@@ -20880,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",
@@ -20895,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: [
           {
@@ -20909,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}`,
@@ -20930,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}`);
       }
@@ -20973,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) {
@@ -21004,7 +21121,7 @@ function formatAddResult(result) {
   }
   return lines.join("\n");
 }
-function registerAddTool(server, getLibrary) {
+function registerAddTool(server, getLibraryOperations) {
   server.registerTool(
     "add",
     {
@@ -21014,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: [
           {
@@ -21029,7 +21146,7 @@ function registerAddTool(server, getLibrary) {
     }
   );
 }
-function registerCiteTool(server, getLibrary) {
+function registerCiteTool(server, getLibraryOperations) {
   server.registerTool(
     "cite",
     {
@@ -21041,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"
@@ -21056,7 +21173,7 @@ function registerCiteTool(server, getLibrary) {
     }
   );
 }
-function registerFulltextAttachTool(server, getLibrary, getConfig) {
+function registerFulltextAttachTool(server, getLibraryOperations, getConfig) {
   server.registerTool(
     "fulltext_attach",
     {
@@ -21067,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,
@@ -21093,7 +21210,7 @@ function registerFulltextAttachTool(server, getLibrary, getConfig) {
     }
   );
 }
-function registerFulltextGetTool(server, getLibrary, getConfig) {
+function registerFulltextGetTool(server, getLibraryOperations, getConfig) {
   server.registerTool(
     "fulltext_get",
     {
@@ -21103,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
       });
@@ -21117,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,
@@ -21146,7 +21263,7 @@ function registerFulltextGetTool(server, getLibrary, getConfig) {
     }
   );
 }
-function registerFulltextDetachTool(server, getLibrary, getConfig) {
+function registerFulltextDetachTool(server, getLibraryOperations, getConfig) {
   server.registerTool(
     "fulltext_detach",
     {
@@ -21156,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
       });
@@ -21180,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",
     {
@@ -21224,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: [
@@ -21249,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 = {
@@ -21296,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
@@ -21381,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";
@@ -21397,17 +21560,101 @@ 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");
+}
+function validateInteractiveOptions(options) {
+  const outputOptions = [options.json, options.idsOnly, options.uuid, options.bibtex].filter(
+    Boolean
+  );
+  if (outputOptions.length > 0) {
+    throw new Error(
+      "Interactive mode cannot be combined with output format options (--json, --ids-only, --uuid, --bibtex)"
+    );
+  }
+}
+async function executeInteractiveSearch(options, context, config2) {
+  validateInteractiveOptions(options);
+  const { checkTTY } = await import("./chunks/tty-CDBIQraQ.js");
+  const { runSearchPrompt } = await import("./chunks/search-prompt-D67WyKrY.js");
+  const { runActionMenu } = await import("./chunks/action-menu-CTtINmWd.js");
+  const { search } = await import("./chunks/file-watcher-D7oyc-9z.js").then((n) => n.y);
+  const { tokenize } = await import("./chunks/file-watcher-D7oyc-9z.js").then((n) => n.x);
+  checkTTY();
+  const allReferences = await context.library.getAll();
+  const searchFn = (query) => {
+    const { tokens } = tokenize(query);
+    return search(allReferences, tokens);
+  };
+  const interactiveConfig = config2.cli.interactive;
+  const searchResult = await runSearchPrompt(
+    allReferences,
+    searchFn,
+    {
+      limit: interactiveConfig.limit,
+      debounceMs: interactiveConfig.debounceMs
+    },
+    options.query || ""
+  );
+  if (searchResult.cancelled || searchResult.selected.length === 0) {
+    return { output: "", cancelled: true };
+  }
+  const actionResult = await runActionMenu(searchResult.selected);
+  return {
+    output: actionResult.output,
+    cancelled: actionResult.cancelled
+  };
 }
 async function serverStart(options) {
   const existingStatus = await serverStatus(options.portfilePath);
@@ -21516,47 +21763,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-Bl_mOQRe.js").then((n) => n.h);
-    return searchReferences2(this.library, options);
-  }
-  async list(options) {
-    const { listReferences: listReferences2 } = await import("./chunks/index-Bl_mOQRe.js").then((n) => n.g);
-    return listReferences2(this.library, options ?? {});
-  }
-  async cite(options) {
-    const { citeReferences: citeReferences2 } = await import("./chunks/index-Bl_mOQRe.js").then((n) => n.f);
-    return citeReferences2(this.library, options);
-  }
-  async import(inputs, options) {
-    const { addReferences: addReferences2 } = await import("./chunks/index-Bl_mOQRe.js").then((n) => n.e);
-    return addReferences2(inputs, this.library, options ?? {});
-  }
-}
 class ServerClient {
   constructor(baseUrl) {
     this.baseUrl = baseUrl;
@@ -21786,6 +21992,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) {
@@ -21897,6 +22296,7 @@ function createProgram() {
   registerServerCommand(program);
   registerFulltextCommand(program);
   registerMcpCommand(program);
+  registerCompletionCommand(program);
   return program;
 }
 async function handleListAction(options, program) {
@@ -21905,7 +22305,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}
 `);
@@ -21918,7 +22318,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);
   });
 }
@@ -21927,8 +22327,16 @@ async function handleSearchAction(query, options, program) {
     const globalOpts = program.opts();
     const config2 = await loadConfigWithOverrides({ ...globalOpts, ...options });
     const context = await createExecutionContext(config2, Library.load);
+    if (options.interactive) {
+      const result2 = await executeInteractiveSearch({ ...options, query }, context, config2);
+      if (result2.output) {
+        process.stdout.write(`${result2.output}
+`);
+      }
+      process.exit(result2.cancelled ? 0 : 0);
+    }
     const result = await executeSearch({ ...options, query }, context);
-    const output = formatSearchOutput(result);
+    const output = formatSearchOutput(result, options.json ?? false);
     if (output) {
       process.stdout.write(`${output}
 `);
@@ -21941,8 +22349,12 @@ 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) => {
-    await handleSearchAction(query, options, program);
+  program.command("search").description("Search references").argument("[query]", "Search query (required unless using --interactive)").option("-i, --interactive", "Enable interactive search mode").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) => {
+    if (!options.interactive && !query) {
+      process.stderr.write("Error: Search query is required unless using --interactive\n");
+      process.exit(1);
+    }
+    await handleSearchAction(query ?? "", options, program);
   });
 }
 async function handleAddAction(inputs, options, program) {
@@ -22389,6 +22801,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);
   });