@ncukondo/search-hub 0.20.0 → 0.21.0

package/dist/cli/index.js

@@ -17,7 +17,8 @@ import { createEricCountValidator, createEmtreeCountValidator } from "../query/v
 import { createProviderInstance, executePreview, executeCountOnly, executeSearch } from "./commands/search-executor.js";
 import { translateQueryCommand, formatTranslateResult } from "./commands/query/translate.js";
 import { inspectQueryCommand, formatInspectOutput } from "./commands/query/inspect.js";
-import { writeQueryTemplate, generateQueryTemplate } from "./commands/query/init.js";
+import { writeQueryTemplate } from "./commands/query/init.js";
+import { resolveQueryFile } from "./commands/query/resolve.js";
 import { getSessionDetails, computeDeduplicationStats, formatSessionDetails, listSessionsForDisplay, formatSessionList } from "./commands/status.js";
 import { parseSearchOptions, validateSearchInput, formatShortKeywordWarning, formatDryRunOutput, formatPreviewOutput, formatCountOnlyOutput } from "./commands/search.js";
 import { parseResumeOptions, validateResumeInput, getResumableProvidersForCommand } from "./commands/resume.js";
@@ -42,7 +43,7 @@ import { executeReviewFinalize, formatFinalizeOutput } from "./commands/review/f
 import "zod";
 import "./commands/review/schema.js";
 import { registerFulltextCommands } from "./commands/fulltext/index.js";
-import { parseRegisterOptions, validateRegisterInput, hasReviewFile, getReviewSummary, formatNoIncludedArticlesError, formatPendingWarning, confirmPrompt, getIncludedArticles, formatReviewRequiredMessage, formatIgnoringReviewsNote, formatDryRunOutput as formatDryRunOutput$1, formatRegistrationSummary } from "./commands/register.js";
+import { parseRegisterOptions, validateRegisterInput, hasReviewFile, getReviewSummary, formatNoIncludedArticlesError, formatPendingWarning, confirmPrompt, getIncludedArticles, formatReviewRequiredMessage, formatIgnoringReviewsNote, formatDryRunOutput as formatDryRunOutput$1, formatRegistrationSummary, formatLibraryPath, formatDefaultLibraryHint } from "./commands/register.js";
 import { formatSuggestion } from "./suggestions/index.js";
 import { getSuggestion } from "./suggestions/rules.js";
 import { readLogEntries, computeQueryHash, appendLogEntry, buildPreviewLogEntry, buildCountLogEntry } from "./commands/query/iteration-log.js";
@@ -77,10 +78,10 @@ Workflow:
   Iterate: search → results -q → check → diff       Query refinement
 
 Quick Start:
-  $ search-hub query init -o search.yaml        # Create query template
-  $ search-hub search search.yaml --count-only  # Check hit counts
-  $ search-hub search search.yaml               # Execute search
-  $ search-hub results <session>                # Review titles`);
+  $ search-hub query init "my search"            # Create query template
+  $ search-hub search my-search --count-only     # Check hit counts
+  $ search-hub search my-search                  # Execute search
+  $ search-hub results <session>                 # Review titles`);
   program.command("init").description("Initialize configuration directory").option("-f, --force", "overwrite existing configuration", false).addHelpText("after", `
 Examples:
   $ search-hub init                 # Initialize with default settings
@@ -190,9 +191,10 @@ Use "search-hub query init" to generate a template.`);
 Examples:
   $ search-hub query validate ./diabetes-ai.yaml
   $ search-hub query validate ./diabetes-ai.yaml --no-vocab   # Skip MeSH check
-  $ search-hub query validate ./diabetes-ai.yaml --no-cache   # Ignore cache`).action(async (file, opts) => {
+  $ search-hub query validate ./diabetes-ai.yaml --no-cache   # Ignore cache`).action(async (fileArg, opts) => {
     const globalOpts = program.opts();
     try {
+      const file = await resolveQueryFile(fileArg);
       const noVocab = opts.vocab === false;
       const noCache = opts.cache === false;
       let cache;
@@ -279,9 +281,10 @@ Examples:
   queryCommand.command("translate").description("Show translated queries for each database").argument("<file>", "path to query YAML file").option("--db <provider>", "show translation for specific provider only").addHelpText("after", `
 Examples:
   $ search-hub query translate ./diabetes-ai.yaml            # All databases
-  $ search-hub query translate ./diabetes-ai.yaml --db pubmed # PubMed only`).action(async (file, options) => {
+  $ search-hub query translate ./diabetes-ai.yaml --db pubmed # PubMed only`).action(async (fileArg, options) => {
     const globalOpts = program.opts();
     try {
+      const file = await resolveQueryFile(fileArg);
       const translateOptions = options.db ? { providers: [options.db] } : {};
       const result = await translateQueryCommand(file, translateOptions);
       if (!globalOpts.quiet) {
@@ -301,9 +304,10 @@ Examples:
   queryCommand.command("inspect").description("Show how a query resolves per provider (block replacements and added filters)").argument("<file>", "path to query YAML file").option("--db <provider>", "show resolution for specific provider only").addHelpText("after", `
 Examples:
   $ search-hub query inspect ./diabetes-ai.yaml            # All databases
-  $ search-hub query inspect ./diabetes-ai.yaml --db pubmed # PubMed only`).action(async (file, options) => {
+  $ search-hub query inspect ./diabetes-ai.yaml --db pubmed # PubMed only`).action(async (fileArg, options) => {
     const globalOpts = program.opts();
     try {
+      const file = await resolveQueryFile(fileArg);
       const inspectOptions = options.db ? { providers: [options.db] } : {};
       const result = await inspectQueryCommand(file, inspectOptions);
       if (!result.success) {
@@ -328,24 +332,35 @@ Examples:
       process.exitCode = EXIT_CODES.QUERY_ERROR;
     }
   });
-  queryCommand.command("init").description("Generate a template query YAML file").option("-o, --output <path>", "write to file (default: stdout)").option("--force", "overwrite existing file", false).action(async (options) => {
+  queryCommand.command("init").description("Generate a template query YAML file").argument("<title>", "query title (used for name field and filename)").option("-o, --output <path>", "write to specific file path").option("--stdout", "output to stdout instead of file").option("--force", "overwrite existing file", false).addHelpText("after", `
+Examples:
+  $ search-hub query init "WBA pain mechanisms"              # → queries/wba-pain-mechanisms.yaml
+  $ search-hub query init "WBA pain" -o ./custom-path.yaml   # Custom output path
+  $ search-hub query init "WBA pain" --stdout                # Print to stdout`).action(async (title, options) => {
     const globalOpts = program.opts();
     try {
-      if (options.output) {
-        const result = await writeQueryTemplate(options);
-        if (!globalOpts.quiet) {
-          if (result.success) {
-            console.log(result.message);
-          } else {
-            console.error(result.message);
+      const result = await writeQueryTemplate({
+        title,
+        output: options.output,
+        stdout: options.stdout,
+        force: options.force
+      });
+      if (!globalOpts.quiet) {
+        if (result.success) {
+          console.log(result.message);
+          if (result.outputPath) {
+            const suggestion = formatSuggestion(getSuggestion({
+              command: "query init",
+              outputFile: result.outputPath
+            }));
+            if (suggestion) console.log("\n" + suggestion);
+            console.log("\nIterate: edit the same file and re-run step 3. Counts are logged automatically.");
           }
+        } else {
+          console.error(result.message);
         }
-        process.exitCode = result.success ? EXIT_CODES.SUCCESS : EXIT_CODES.GENERAL_ERROR;
-      } else {
-        const template = generateQueryTemplate();
-        console.log(template);
-        process.exitCode = EXIT_CODES.SUCCESS;
       }
+      process.exitCode = result.success ? EXIT_CODES.SUCCESS : EXIT_CODES.GENERAL_ERROR;
     } catch (error) {
       if (!globalOpts.quiet) {
         console.error("Error:", error instanceof Error ? error.message : error);
@@ -356,9 +371,10 @@ Examples:
   queryCommand.command("assess").description("Record an assessment of the current query iteration").argument("<file>", "path to query YAML file").option("--verdict <verdict>", "assessment verdict (e.g., reject, good, refine)").option("--precision <precision>", "estimated precision (e.g., ~60%)").option("--comment <comment>", "free-text comment").addHelpText("after", `
 Examples:
   $ search-hub query assess query.yaml --verdict reject --comment "Too broad"
-  $ search-hub query assess query.yaml --verdict good --precision "~60%"`).action(async (file, options) => {
+  $ search-hub query assess query.yaml --verdict good --precision "~60%"`).action(async (fileArg, options) => {
     const globalOpts = program.opts();
     try {
+      const file = await resolveQueryFile(fileArg);
       const result = await executeQueryAssess(file, options);
       if (result.success) {
         if (!globalOpts.quiet) {
@@ -386,9 +402,10 @@ Examples:
   queryCommand.command("log").description("View the query iteration history").argument("<file>", "path to query YAML file").option("--json", "output as JSON").addHelpText("after", `
 Examples:
   $ search-hub query log query.yaml
-  $ search-hub query log query.yaml --json`).action(async (file, options) => {
+  $ search-hub query log query.yaml --json`).action(async (fileArg, options) => {
     const globalOpts = program.opts();
     try {
+      const file = await resolveQueryFile(fileArg);
       const entries = await readLogEntries(file);
       if (!globalOpts.quiet) {
         console.log(formatLogOutput(entries, { json: options?.json }));
@@ -468,7 +485,8 @@ Query features (use "query init" to see full template):
     async (queryFile, options) => {
       const globalOpts = program.opts();
       try {
-        const searchOpts = parseSearchOptions(queryFile, {
+        const resolvedQueryFile = queryFile ? await resolveQueryFile(queryFile) : void 0;
+        const searchOpts = parseSearchOptions(resolvedQueryFile, {
           db: options?.db,
           query: options?.query,
           name: options?.name,
@@ -683,11 +701,14 @@ Warning: Some providers failed:
             if (result.sessionId) {
               const sessions = await listSessions(sessionsDir);
               const suggestionCmd = searchOpts.directQuery ? "search --query" : "search";
+              const currentSession = sessions.find((s) => s.id === result.sessionId);
+              const previousSession = currentSession ? sessions.filter((s) => s.name === currentSession.name && s.id !== result.sessionId).sort((a, b) => b.createdAt.localeCompare(a.createdAt))[0] : void 0;
               const suggestion = formatSuggestion(getSuggestion({
                 command: suggestionCmd,
                 sessionId: result.sessionId,
                 sessionStatus: result.sessionStatus,
-                sessionCount: sessions.length
+                sessionCount: sessions.length,
+                previousSessionId: previousSession?.id
               }));
               if (suggestion) console.log(suggestion);
             }
@@ -1688,7 +1709,10 @@ Failed to install reference-manager: ${installError instanceof Error ? installEr
             }
           }
           console.log(`
-Results saved to: ${join(sessionDir, "registration.json")}`);
+${formatLibraryPath(sessionDir)}`);
+          console.log(`Results saved to: ${join(sessionDir, "registration.json")}`);
+          console.log(`
+${formatDefaultLibraryHint(sessionDir)}`);
           const suggestion = formatSuggestion(getSuggestion({
             command: "register",
             sessionId,