@ncukondo/search-hub 0.10.0 → 0.12.0

package/dist/cli/index.js

@@ -23,11 +23,12 @@ import { computeSummary, formatSummaryJson, formatSummary } from "./commands/sum
 import { parseResultsOptions, validateResultsInput, formatResultsJson, formatResultsList } from "./commands/results.js";
 import { loadNotes, formatAllSessionNotes, formatNotesList, addNote, addAssessment } from "./commands/notes.js";
 import { computeDiff, computeQueryDiff, formatDiffJson, formatDiff } from "./commands/diff.js";
+import { validateMergeSources, mergeArticles, formatMergeJson, formatMergeOutput, createMergedSession } from "./commands/merge.js";
 import { executeReviewInit } from "./commands/review/init.js";
 import { executeReviewStatus, formatStatusOutput } from "./commands/review/status.js";
 import { executeReviewList, formatListOutput } from "./commands/review/list.js";
 import { executeReviewExtract } from "./commands/review/extract.js";
-import { executeReviewMerge, formatMergeOutput } from "./commands/review/merge.js";
+import { executeReviewMerge, formatMergeOutput as formatMergeOutput$1 } from "./commands/review/merge.js";
 import { executeReviewMark } from "./commands/review/mark.js";
 import { executeReviewExport, formatExportOutput } from "./commands/review/export.js";
 import { executeReviewFinalize, formatFinalizeOutput } from "./commands/review/finalize.js";
@@ -295,7 +296,13 @@ Examples:
   $ search-hub search --db pubmed --query "diabetes[tiab]"  # Direct query
   $ search-hub search ./query.yaml --dry-run            # Preview translations
   $ search-hub search ./query.yaml --count-only         # Get hit counts only
-  $ search-hub search ./query.yaml --max-results 100    # Limit results`).action(
+  $ search-hub search ./query.yaml --max-results 100    # Limit results
+
+Query features (use "query init" to see full template):
+  filters:    year_from, year_to, language, publication_types
+  exclude:    NOT terms per block (terms.exclude)
+  mesh/eric:  controlled vocabulary (terms.mesh, terms.eric)
+  overrides:  per-database settings (pubmed, scopus, eric, arxiv)`).action(
     async (queryFile, options) => {
       const globalOpts = program.opts();
       try {
@@ -967,6 +974,135 @@ Query Refinement Workflow:
         } else {
           if (!globalOpts.quiet) {
             console.log(formatDiff(diff, sessionId1, sessionId2, showFilter, formatOptions));
+            const suggestion = formatSuggestion(getSuggestion({
+              command: "diff",
+              sessionId: sessionId2,
+              diffSession1Id: sessionId1,
+              diffAddedCount: diff.added.length,
+              diffRemovedCount: diff.removed.length
+            }));
+            if (suggestion) {
+              console.log(suggestion);
+            }
+          }
+        }
+        process.exitCode = EXIT_CODES.SUCCESS;
+      } catch (error) {
+        if (!globalOpts.quiet) {
+          console.error(
+            "Error:",
+            error instanceof Error ? error.message : error
+          );
+        }
+        process.exitCode = EXIT_CODES.SESSION_ERROR;
+      }
+    }
+  );
+  program.command("merge").description("Merge results from multiple search sessions").argument("<session-ids...>", "two or more session IDs to merge").option("--name <string>", "name for merged session").option("--dry-run", "show what would be merged without creating session").option("--json", "output as JSON").addHelpText("after", `
+Examples:
+  $ search-hub merge session-v4 session-v9                  # Merge two sessions
+  $ search-hub merge session-v4 session-v9 --name combined  # Merge with custom name
+  $ search-hub merge session-a session-b session-c          # Merge three sessions
+  $ search-hub merge session-v4 session-v9 --dry-run        # Preview merge`).action(
+    async (sessionIds, options) => {
+      const globalOpts = program.opts();
+      try {
+        if (sessionIds.length < 2) {
+          if (!globalOpts.quiet) {
+            console.error("Error: At least two session IDs are required for merge");
+          }
+          process.exitCode = EXIT_CODES.GENERAL_ERROR;
+          return;
+        }
+        const sessionsDir = await getSessionsDir(globalOpts);
+        const sessions = /* @__PURE__ */ new Map();
+        for (const sessionId of sessionIds) {
+          try {
+            const session = await loadSession(sessionId, sessionsDir);
+            sessions.set(sessionId, session);
+          } catch (error) {
+            if (!globalOpts.quiet) {
+              console.error(
+                `Error loading session '${sessionId}': ${error instanceof Error ? error.message : "Failed to load session"}`
+              );
+            }
+            process.exitCode = EXIT_CODES.SESSION_ERROR;
+            return;
+          }
+        }
+        const validation = validateMergeSources(sessions);
+        if (!validation.valid) {
+          if (!globalOpts.quiet) {
+            console.error(`Error: ${validation.error}`);
+          }
+          process.exitCode = EXIT_CODES.SESSION_ERROR;
+          return;
+        }
+        const sessionArticles = /* @__PURE__ */ new Map();
+        for (const [sessionId, session] of sessions) {
+          const articles = await loadSessionArticles(session, sessionId, sessionsDir);
+          sessionArticles.set(sessionId, articles);
+        }
+        const mergeResult = mergeArticles(sessionArticles);
+        const sources = [...sessions.entries()].map(([id, session]) => ({
+          id,
+          name: session.name,
+          count: mergeResult.perSession.get(id) ?? 0
+        }));
+        const byProviderCounts = /* @__PURE__ */ new Map();
+        for (const [provider, articles] of mergeResult.byProvider) {
+          byProviderCounts.set(provider, articles.length);
+        }
+        const firstSession = sessions.values().next().value;
+        const mergeName = options?.name ?? (firstSession ? firstSession.name + "-merged" : "merged");
+        if (options?.dryRun) {
+          const outputData2 = {
+            sessionId: "(dry-run)",
+            totalBefore: mergeResult.totalBefore,
+            totalAfter: mergeResult.totalAfter,
+            duplicatesRemoved: mergeResult.duplicatesRemoved,
+            sources,
+            byProvider: byProviderCounts
+          };
+          if (options.json) {
+            console.log(formatMergeJson(outputData2));
+          } else if (!globalOpts.quiet) {
+            console.log(formatMergeOutput(outputData2));
+          }
+          process.exitCode = EXIT_CODES.SUCCESS;
+          return;
+        }
+        const sessionSources = [...sessions.entries()].map(([id, session]) => ({
+          id,
+          name: session.name
+        }));
+        const mergedSession = await createMergedSession({
+          name: mergeName,
+          sources: sessionSources,
+          byProvider: mergeResult.byProvider,
+          totalRetrieved: mergeResult.totalAfter,
+          sessionsDir,
+          sourceSessionIds: sessionIds
+        });
+        const outputData = {
+          sessionId: mergedSession.id,
+          totalBefore: mergeResult.totalBefore,
+          totalAfter: mergeResult.totalAfter,
+          duplicatesRemoved: mergeResult.duplicatesRemoved,
+          sources,
+          byProvider: byProviderCounts
+        };
+        if (options?.json) {
+          console.log(formatMergeJson(outputData));
+        } else if (!globalOpts.quiet) {
+          console.log(formatMergeOutput(outputData));
+          const suggestion = getSuggestion({
+            command: "merge",
+            sessionId: mergedSession.id
+          });
+          const suggestionText = formatSuggestion(suggestion);
+          if (suggestionText) {
+            console.log(suggestionText);
           }
         }
         process.exitCode = EXIT_CODES.SUCCESS;
@@ -1258,7 +1394,7 @@ Examples:
       process.exitCode = EXIT_CODES.SESSION_ERROR;
     }
   });
-  reviewCommand.command("extract").description("Extract subset to for-review/<name>/review.yaml for distributed review").requiredOption("--session <id>", "session ID").requiredOption("--name <name>", "name for the review subset (output: for-review/<name>/review.yaml)").option("--filter <types>", "filter by status (comma-separated): pending, incomplete, uncertain, agreed-include, agreed-exclude, conflicting, finalized").option("--sort <method>", "sort method: year, title, random, none", "none").option("--limit <n>", "limit number of articles").option("--offset <n>", "skip first n articles").option("--seed <n>", "random seed for reproducible sorting").option("--basis <type>", "basis for review: title or abstract (outputs work file format)").option("--reviewer <id>", 'reviewer identifier (e.g., "ai:claude")').action(async (options) => {
+  reviewCommand.command("extract").description("Extract subset to for-review/<name>/review.yaml for distributed review").requiredOption("--session <id>", "session ID").requiredOption("--name <name>", "name for the review subset (output: for-review/<name>/review.yaml)").option("--filter <types>", "filter by status (comma-separated): pending, incomplete, uncertain, agreed-include, agreed-exclude, conflicting, finalized").option("--sort <method>", "sort method: year, title, random, none", "none").option("--limit <n>", "limit number of articles").option("--offset <n>", "skip first n articles").option("--seed <n>", "random seed for reproducible sorting").option("--basis <type>", "basis for review: title, abstract, or fulltext").option("--reviewer <id>", 'reviewer identifier (e.g., "ai:claude")').option("--finalize", "extract for final decision (includes reviewHistory and finalDecision)").action(async (options) => {
     const globalOpts = program.opts();
     try {
       const validSorts = ["year", "title", "random", "none"];
@@ -1307,6 +1443,9 @@ Examples:
         }
         extractOptions.basis = options.basis;
       }
+      if (options.finalize) {
+        extractOptions.finalize = true;
+      }
       const result = await executeReviewExtract(extractOptions, sessionsDir);
       if (!globalOpts.quiet) {
         console.log(`Extracted ${result.extractedCount} of ${result.totalMatching} articles to ${result.outputPath}`);
@@ -1340,7 +1479,7 @@ Examples:
       };
       const result = await executeReviewMerge(mergeOptions, sessionsDir);
       if (!globalOpts.quiet) {
-        console.log(formatMergeOutput(result, options.dryRun));
+        console.log(formatMergeOutput$1(result, options.dryRun));
         if (!options.dryRun) {
           const statusResult = await executeReviewStatus({ sessionId: options.session }, sessionsDir);
           const suggestion = formatSuggestion(getSuggestion({