fix: expose Alexandria help in beta releases

src/__tests__/alexandria-beta.test.ts

@@ -71,13 +71,16 @@ async function cli(args: string[], key = 'fc-test') {
   }
 }
 
-it('keeps beta options out of normal help and respects explicit web-only search', async () => {
-  for (const args of [['--help'], ['search', '--help'], ['scrape', '--help']]) {
-    const result = await cli(args);
+it('shows Alexandria beta help and respects explicit web-only search', async () => {
+  for (const [args, expected] of [
+    [['--help'], 'find-tools'],
+    [['search', '--help'], '--domain-tools'],
+    [['scrape', '--help'], '--alexandria'],
+  ] as const) {
+    const result = await cli([...args]);
     expect(result.code).toBe(0);
-    expect(result.stdout).not.toMatch(
-      /alexandria|find-tools|domain-tools|--enable/i
-    );
+    expect(result.stdout).toContain(expected);
+    expect(result.stdout).not.toContain('--enable');
   }
   response = { success: true, data: { web: [] } };
   const result = await cli([

src/commands/alexandria.ts

@@ -124,6 +124,9 @@ export async function handleAlexandria(
 
 export function createFindToolsCommand(): Command {
   return new Command('find-tools')
+    .description(
+      'Explore Alexandria providers and tool contracts without executing them'
+    )
     .argument('[urls...]')
     .option('--options <json>', 'Find Tools catalogue filters')
     .option(
@@ -162,24 +165,43 @@ export function createFindToolsCommand(): Command {
     });
 }
 
-export function addAlexandriaScrapeOptions(command: Command): void {
+export function addAlexandriaScrapeOptions(
+  command: Command,
+  visible = false
+): void {
   command
     .addOption(
-      new Option('--alexandria <provider/capability>')
+      new Option(
+        '--alexandria <provider/capability>',
+        'Execute an Alexandria tool; repeat for a batch'
+      )
         .argParser((value: string, previous: string[] = []) => [
           ...previous,
           value,
         ])
-        .hideHelp()
+        .hideHelp(!visible)
     )
     .addOption(
-      new Option('--options <json>')
+      new Option(
+        '--options <json>',
+        'JSON inputs paired with each Alexandria tool'
+      )
         .argParser((value: string, previous: string[] = []) => [
           ...previous,
           value,
         ])
-        .hideHelp()
+        .hideHelp(!visible)
+    )
+    .addOption(
+      new Option(
+        '--request-id <id>',
+        'Optional ID for an identical retry'
+      ).hideHelp(!visible)
     )
-    .addOption(new Option('--request-id <id>').hideHelp())
-    .addOption(new Option('--domain-tools').hideHelp());
+    .addOption(
+      new Option(
+        '--domain-tools',
+        'Include matching tool contracts with a URL scrape'
+      ).hideHelp(!visible)
+    );
 }

src/index.ts

@@ -75,6 +75,8 @@ import { isJobId } from './utils/job';
 import { ensureAuthenticated, printBanner } from './utils/auth';
 import { maybeShowUpdateNotice } from './utils/update-notice';
 import packageJson from '../package.json';
+
+const showAlexandriaHelp = packageJson.version.includes('alexandria');
 import type { SearchSource, SearchCategory } from './types/search';
 import type { ScrapeFormat } from './types/scrape';
 import type { RelatedPapersOptions } from './types/research';
@@ -530,7 +532,7 @@ function createScrapeCommand(): Command {
       }
     });
 
-  addAlexandriaScrapeOptions(scrapeCmd);
+  addAlexandriaScrapeOptions(scrapeCmd, showAlexandriaHelp);
   return scrapeCmd;
 }
 
@@ -940,7 +942,9 @@ function createSearchCommand(): Command {
     )
     .option(
       '--sources <sources>',
-      'Comma-separated sources to search: web, images, news (default: web)'
+      showAlexandriaHelp
+        ? 'Comma-separated sources: web, images, news, alexandria (default: web,alexandria; domain tools enabled)'
+        : 'Comma-separated sources to search: web, images, news (default: web)'
     )
     .option(
       '--categories <categories>',
@@ -1070,7 +1074,11 @@ function createSearchCommand(): Command {
       await handleSearchCommand(searchOptions);
     });
 
-  searchCmd.addOption(new Option('--domain-tools').hideHelp());
+  searchCmd.addOption(
+    new Option('--domain-tools', 'Discover tools for result domains').hideHelp(
+      !showAlexandriaHelp
+    )
+  );
   return searchCmd;
 }
 
@@ -2118,7 +2126,7 @@ program.addCommand(createMapCommand());
 program.addCommand(createParseCommand());
 program.addCommand(createMonitorCommand());
 program.addCommand(createSearchCommand());
-program.addCommand(createFindToolsCommand(), { hidden: true });
+program.addCommand(createFindToolsCommand(), { hidden: !showAlexandriaHelp });
 program.addCommand(createDeveloperCommand());
 program.addCommand(createResearchCommand());
 program.addCommand(createFeedbackCommand());