paper-manager 0.11.0 → 0.11.2

package/README.md

@@ -5,6 +5,20 @@
 
 A CLI tool for managing academic papers with knowledge base and vector search support.
 
+## Features
+
+- **Semantic search** — FAISS vector indexing with configurable embedding models, query your papers by meaning rather than keywords
+- **PDF metadata extraction** — automatically extracts title, author, keywords, DOI, and more from PDF files
+- **DOI deduplication** — detects duplicate papers by DOI before adding, with `--force` override
+- **Multi-format support** — import from PDF, TXT, MD, TEX, and other text-based formats
+- **PDF-to-Markdown conversion** — optional high-quality conversion via [opendataloader-pdf](https://github.com/nicobailon/opendataloader-pdf) with image extraction
+- **Dual-scope data model** — user-level (`~/.paper-manager/`) for global collections and project-level (`./.paper-manager/`) for project-specific papers, with automatic scope resolution
+- **DOI-to-BibTeX** — convert DOI to BibTeX citation in one command
+- **Machine-readable output** — `--json` and `--jq` flags on all read commands for scripting and automation
+- **Literature notes** — attach key-value annotations to any paper
+- **Local-first** — SQLite + FAISS + filesystem, no cloud dependencies
+- **Agent skill** — installable as a [coding agent skill](https://github.com/vercel-labs/skills) for agent-driven paper management
+
 ## Installation
 
 ```bash
@@ -64,7 +78,7 @@ paper kb query <id> <query-text> [--json] [--jq <expr>]  # Query a knowledge bas
 ### Literature (`paper lit`)
 
 ```bash
-paper lit add <kb-id> <file-path>     # Add a literature (auto-extracts PDF metadata)
+paper lit add <kb-id> <file-path> [-f] # Add a literature (auto-extracts PDF metadata, rejects duplicate DOI)
 paper lit remove <kb-id> <id>         # Remove a literature
 paper lit update <kb-id> <id> [opts]  # Update literature metadata
 paper lit list <kb-id> [--json] [--jq <expr>]       # List literatures

package/dist/commands/literature.js

@@ -36,6 +36,7 @@ export function createLiteratureCommand() {
         .command("add <knowledge-base-id> <lit-path>")
         .description("Add a literature from a file (PDF, TXT, MD, TEX, etc.)")
         .option("-t, --title <title>", "Literature title")
+        .option("-f, --force", "Force add even if a literature with the same DOI already exists")
         .action(async (kbId, litPath, options) => {
         const resolved = resolveKnowledgeBase(kbId);
         if (!resolved) {
@@ -77,6 +78,15 @@ export function createLiteratureCommand() {
                     log.step(`Creator: ${pdfMeta.creator}`);
             }
         }
+        // Check for duplicate DOI in the knowledge base
+        if (pdfMeta?.doi && !options.force) {
+            const existing = litOps.findLiteratureByDoi(kbId, pdfMeta.doi);
+            if (existing) {
+                log.error(`A literature with DOI "${pdfMeta.doi}" already exists in this knowledge base: ${existing.id} (${existing.title})`);
+                log.info("Use --force to add anyway.");
+                process.exit(1);
+            }
+        }
         const title = options.title ?? pdfMeta?.title ?? path.basename(litPath, path.extname(litPath));
         // Create literature record
         const literature = litOps.createLiterature({

package/dist/config/index.js

@@ -5,12 +5,45 @@ import * as z from "zod";
 import { EmbeddingModelConfigSchema } from "../types/index.js";
 // ─── Path Utilities ─────────────────────────────────────────
 const USER_DATA_DIR = path.join(os.homedir(), ".paper-manager");
-const PROJECT_DATA_DIR = path.resolve(".paper-manager");
+const DIR_NAME = ".paper-manager";
+function findProjectDataDir() {
+    let dir = process.cwd();
+    while (true) {
+        const candidate = path.join(dir, DIR_NAME);
+        if (fs.existsSync(candidate))
+            return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    // Fallback: CWD (no .paper-manager/ found up the tree)
+    return path.resolve(DIR_NAME);
+}
+let cachedProjectDataDir;
 export function getUserDataDir() {
     return USER_DATA_DIR;
 }
+/**
+ * Returns the project-level `.paper-manager/` directory path, traversing
+ * up from CWD. Falls back to CWD if not found. Result is cached per process.
+ */
 export function getProjectDataDir() {
-    return PROJECT_DATA_DIR;
+    if (cachedProjectDataDir === undefined) {
+        cachedProjectDataDir = findProjectDataDir();
+    }
+    return cachedProjectDataDir;
+}
+/** @internal Reset cached project data dir. For testing only. */
+export function resetProjectDataDirCache() {
+    cachedProjectDataDir = undefined;
+}
+/**
+ * Returns CWD-based `.paper-manager/` path without traversal.
+ * Used by `config init` to always create in the current directory.
+ */
+export function getProjectInitDir() {
+    return path.resolve(DIR_NAME);
 }
 export function getFilesDir(base) {
     return path.join(base, "files");
@@ -22,7 +55,7 @@ function getUserConfigPath() {
     return path.join(USER_DATA_DIR, "config.json");
 }
 function getProjectConfigPath() {
-    return path.join(PROJECT_DATA_DIR, "config.json");
+    return path.join(getProjectDataDir(), "config.json");
 }
 // ─── Config Schema Map ─────────────────────────────────────
 const configSchemas = {

package/dist/config/init.js

@@ -1,9 +1,9 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { initializeDatabase, openDatabase } from "../db/index.js";
-import { getFilesDir, getProjectDataDir, getUserDataDir, getVectorStoreDir, writeConfigFile, } from "./index.js";
+import { getFilesDir, getProjectInitDir, getUserDataDir, getVectorStoreDir, writeConfigFile, } from "./index.js";
 export function initScope(options) {
-    const baseDir = options?.user ? getUserDataDir() : getProjectDataDir();
+    const baseDir = options?.user ? getUserDataDir() : getProjectInitDir();
     const items = [];
     // 1. Base directory
     if (fs.existsSync(baseDir)) {

package/dist/db/operations/literatures.js

@@ -85,6 +85,14 @@ export function updateLiterature(db, id, input) {
     const row = db.update(literatures).set(updates).where(eq(literatures.id, id)).returning().get();
     return row ?? null;
 }
+export function findLiteratureByDoi(db, knowledgeBaseId, doi) {
+    const row = db
+        .select()
+        .from(literatures)
+        .where(and(eq(literatures.knowledgeBaseId, knowledgeBaseId), eq(literatures.doi, doi)))
+        .get();
+    return row ?? null;
+}
 export function deleteLiterature(db, id) {
     const result = db.delete(literatures).where(eq(literatures.id, id)).run();
     return result.changes > 0;

package/dist/db/project/literatures.js

@@ -21,6 +21,9 @@ export function deleteLiteraturesByKnowledgeBaseId(knowledgeBaseId) {
 export function searchLiteratures(knowledgeBaseId, filters) {
     return ops.searchLiteratures(getProjectDb(), knowledgeBaseId, filters);
 }
+export function findLiteratureByDoi(knowledgeBaseId, doi) {
+    return ops.findLiteratureByDoi(getProjectDb(), knowledgeBaseId, doi);
+}
 export function getLiteraturesByKnowledgeBaseId(knowledgeBaseId) {
     return ops.getLiteraturesByKnowledgeBaseId(getProjectDb(), knowledgeBaseId);
 }

package/dist/db/user/literatures.js

@@ -21,6 +21,9 @@ export function deleteLiteraturesByKnowledgeBaseId(knowledgeBaseId) {
 export function searchLiteratures(knowledgeBaseId, filters) {
     return ops.searchLiteratures(getUserDb(), knowledgeBaseId, filters);
 }
+export function findLiteratureByDoi(knowledgeBaseId, doi) {
+    return ops.findLiteratureByDoi(getUserDb(), knowledgeBaseId, doi);
+}
 export function getLiteraturesByKnowledgeBaseId(knowledgeBaseId) {
     return ops.getLiteraturesByKnowledgeBaseId(getUserDb(), knowledgeBaseId);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paper-manager",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "description": "A paper management system.",
   "keywords": [],
   "homepage": "https://github.com/EurFelux/paper-manager",