outrank-cli 0.5.0 → 0.6.0

package/src/commands/keywords.js

@@ -1,14 +1,18 @@
 import {
-  parseArgs,
-  getRequiredPositional,
-  readJsonInput,
-  hasFlag,
-  parseIntegerOption,
-  getOption,
-  getOptions,
-} from '../core/args.js';
-import { requestAgentApi } from '../core/api.js';
-import { cliSuccess } from '../core/errors.js';
+  KEYWORDS_GENERATE_MAX_COUNT,
+  KEYWORDS_GENERATE_MIN_COUNT,
+  KEYWORDS_SUGGEST_MAX_LIMIT,
+  LIST_MAX_LIMIT,
+  LIST_MIN_LIMIT,
+  MAX_DIFFICULTY,
+  MIN_DIFFICULTY,
+  MIN_OFFSET,
+  MIN_SEARCH_VOLUME,
+  Surface,
+} from '../core/constants.js';
+import { MCP_USAGE_GUIDANCE, usageError } from '../core/errors.js';
+import { int, list, oneOf, string, uuid } from '../core/schema.js';
+import { BodyMode, CommandKind, Toolset, defineCommand, defineGroup } from './registry.js';
 
 export const KEYWORDS_HELP = `Usage:
   outrank-cli keywords list --product <product-id> [--scope scheduled|stored|all] [--status published|scheduled|generating_article|pregenerated|disabled] [--q <text>] [--article-type <value>] [--article-subtype <value>] [--scheduled-from <date>] [--scheduled-to <date>] [--search-volume-min <n>] [--search-volume-max <n>] [--difficulty-min <n>] [--difficulty-max <n>] [--limit <n>] [--offset <n>]
@@ -43,262 +47,275 @@ Examples:
   outrank-cli keywords delete 00000000-0000-0000-0000-000000000000
 `;
 
-const buildQueryPath = (basePath, searchParams) => {
-  const url = new URL(`https://local${basePath}`);
-  for (const [key, value] of Object.entries(searchParams)) {
-    if (value !== undefined && value !== null && value !== '') {
-      url.searchParams.set(key, String(value));
-    }
-  }
-  return `${url.pathname}${url.search}`;
-};
-
-const getRequiredProductOption = (parsed) => {
-  const productId = getOption(parsed, 'product');
-  if (!productId) {
-    throw Object.assign(new Error('Missing required option: --product <product-id>.'), {
-      cliCode: 'CLI_INVALID_USAGE',
-      guidance: 'Pass the target product UUID with `--product <product-id>`. Use `outrank-cli products list` if you need to look it up first.',
-    });
-  }
-  return productId;
-};
-
-const handleKeywordsList = async (parsed) => {
-  const path = buildQueryPath('/keywords', {
-    product_id: getRequiredProductOption(parsed),
-    scope: getOption(parsed, 'scope'),
-    status: getOption(parsed, 'status'),
-    q: getOption(parsed, 'q'),
-    article_type: getOption(parsed, 'article-type'),
-    article_subtype: getOption(parsed, 'article-subtype'),
-    scheduled_from: getOption(parsed, 'scheduled-from'),
-    scheduled_to: getOption(parsed, 'scheduled-to'),
-    search_volume_min: parseIntegerOption(parsed, 'search-volume-min', { min: 0 }),
-    search_volume_max: parseIntegerOption(parsed, 'search-volume-max', { min: 0 }),
-    difficulty_min: parseIntegerOption(parsed, 'difficulty-min', { min: 0, max: 100 }),
-    difficulty_max: parseIntegerOption(parsed, 'difficulty-max', { min: 0, max: 100 }),
-    limit: parseIntegerOption(parsed, 'limit', { min: 1, max: 100 }),
-    offset: parseIntegerOption(parsed, 'offset', { min: 0 }),
-  });
-  const response = await requestAgentApi(parsed, {
-    method: 'GET',
-    path,
-  });
-  return response.payload;
-};
-
-const handleKeywordsGet = async (parsed) => {
-  const keywordId = getRequiredPositional(parsed, 0, '<keyword-id>');
-  const path = buildQueryPath(`/keywords/${keywordId}`, {
-    kind: getOption(parsed, 'kind'),
-  });
-  const response = await requestAgentApi(parsed, {
-    method: 'GET',
-    path,
-  });
-  return response.payload;
-};
+const GenerateSource = Object.freeze({ COMPETITORS: 'competitors', AUDIENCES: 'audiences', BOTH: 'both' });
+const GENERATE_SOURCES = Object.values(GenerateSource);
+const KEYWORD_PATH = '/keywords/{keywordId}';
+const KEYWORD_ID_CLI = { positionals: ['keywordId'] };
+const TOOLSETS = [Toolset.KEYWORDS];
 
-const handleKeywordsExport = async (parsed) => {
-  const path = buildQueryPath('/keywords/export', {
-    product_id: getRequiredProductOption(parsed),
-  });
-  const response = await requestAgentApi(parsed, {
-    method: 'GET',
-    path,
-  });
-  return response.payload;
+const PRODUCT_REQUIRED = {
+  guidance:
+    'Pass the target product UUID with `--product <product-id>`. Use `outrank-cli products list` if you need to ' +
+    'look it up first.',
 };
-
-const handleKeywordsGenerationStatus = async (parsed) => {
-  const path = buildQueryPath('/keywords/generation-status', {
-    product_id: getRequiredProductOption(parsed),
-  });
-  const response = await requestAgentApi(parsed, {
-    method: 'GET',
-    path,
-  });
-  return response.payload;
+const COUNT_REQUIRED = {
+  guidance:
+    'Ask the human how many keywords to generate first. The dashboard-equivalent flow allows 5-30 keywords when ' +
+    'enough scheduler slots are free. Use `outrank-cli keywords generation-status --product <product-id>` to ' +
+    'inspect current slot capacity.',
 };
-
-const handleKeywordsAdd = async (parsed) => {
-  const body = await readJsonInput(parsed);
-  body.product_id = getRequiredProductOption(parsed);
-  const response = await requestAgentApi(parsed, {
-    method: 'POST',
-    path: '/keywords',
-    body,
-  });
-  return response.payload;
+const SOURCE_GUIDANCE =
+  'Choose a dashboard generation source with `--source competitors`, `--source audiences`, or `--source both`.';
+const LEGACY_GENERATE_OPTION = {
+  message: 'The generate command no longer accepts --theme or --country.',
+  guidance:
+    'Use `--count`, `--source`, repeated `--competitor`, and repeated `--audience` to match the dashboard ' +
+    'Generate Keywords flow.',
 };
+const SUGGEST_TERM_GUIDANCE = 'Pass either `--keyword <text>` or `--theme <text>` when requesting keyword suggestions.';
 
-const handleKeywordsUpdate = async (parsed) => {
-  const keywordId = getRequiredPositional(parsed, 0, '<keyword-id>');
-  const body = await readJsonInput(parsed);
-  const response = await requestAgentApi(parsed, {
-    method: 'PATCH',
-    path: `/keywords/${keywordId}`,
-    body,
-  });
-  return response.payload;
-};
-
-const handleKeywordsSuggest = async (parsed) => {
-  const keyword = getOption(parsed, 'keyword');
-  const theme = getOption(parsed, 'theme');
-  if (!keyword && !theme) {
-    throw Object.assign(new Error('Missing required option: --keyword <text> or --theme <text>.'), {
-      cliCode: 'CLI_INVALID_USAGE',
-      guidance: 'Pass either `--keyword <text>` or `--theme <text>` when requesting keyword suggestions.',
-    });
-  }
-
-  const body = {
-    product_id: getRequiredProductOption(parsed),
-    ...(keyword ? { keyword } : {}),
-    ...(theme ? { theme } : {}),
-    ...(getOption(parsed, 'keyword-region') ? { keyword_region: getOption(parsed, 'keyword-region') } : {}),
-    ...(parseIntegerOption(parsed, 'limit', { min: 1, max: 20 }) !== undefined
-      ? { limit: parseIntegerOption(parsed, 'limit', { min: 1, max: 20 }) }
-      : {}),
-  };
-
-  const response = await requestAgentApi(parsed, {
-    method: 'POST',
-    path: '/keywords/suggest',
-    body,
-  });
-  return response.payload;
-};
+const productOption = () => uuid().required(PRODUCT_REQUIRED);
+const productCli = { options: { product: 'productId' }, placeholders: { productId: '<product-id>' } };
 
-const handleKeywordsGenerate = async (parsed) => {
-  if (getOption(parsed, 'theme') || getOption(parsed, 'country')) {
-    throw Object.assign(
-      new Error('The generate command no longer accepts --theme or --country.'),
-      {
-        cliCode: 'CLI_INVALID_USAGE',
-        guidance:
-          'Use `--count`, `--source`, repeated `--competitor`, and repeated `--audience` to match the dashboard Generate Keywords flow.',
+const listCommand = defineCommand({
+  id: 'keywords.list',
+  summary: 'List keywords for a product with optional filters and pagination.',
+  kind: CommandKind.READ,
+  toolsets: TOOLSETS,
+  input: {
+    productId: productOption(),
+    scope: string(),
+    status: string(),
+    q: string(),
+    articleType: string(),
+    articleSubtype: string(),
+    scheduledFrom: string(),
+    scheduledTo: string(),
+    searchVolumeMin: int({ min: MIN_SEARCH_VOLUME }),
+    searchVolumeMax: int({ min: MIN_SEARCH_VOLUME }),
+    difficultyMin: int({ min: MIN_DIFFICULTY, max: MAX_DIFFICULTY }),
+    difficultyMax: int({ min: MIN_DIFFICULTY, max: MAX_DIFFICULTY }),
+    limit: int({ min: LIST_MIN_LIMIT, max: LIST_MAX_LIMIT }),
+    offset: int({ min: MIN_OFFSET }),
+  },
+  cli: productCli,
+  run: (input, ctx) =>
+    ctx.http({
+      method: 'GET',
+      path: '/keywords',
+      query: {
+        product_id: input.productId,
+        scope: input.scope,
+        status: input.status,
+        q: input.q,
+        article_type: input.articleType,
+        article_subtype: input.articleSubtype,
+        scheduled_from: input.scheduledFrom,
+        scheduled_to: input.scheduledTo,
+        search_volume_min: input.searchVolumeMin,
+        search_volume_max: input.searchVolumeMax,
+        difficulty_min: input.difficultyMin,
+        difficulty_max: input.difficultyMax,
+        limit: input.limit,
+        offset: input.offset,
       },
-    );
-  }
-
-  const source = getOption(parsed, 'source') || 'both';
-  if (!['competitors', 'audiences', 'both'].includes(source)) {
-    throw Object.assign(new Error('--source must be one of: competitors, audiences, both.'), {
-      cliCode: 'CLI_INVALID_USAGE',
-      guidance:
-        'Choose a dashboard generation source with `--source competitors`, `--source audiences`, or `--source both`.',
-    });
-  }
+    }),
+});
 
-  const competitors = getOptions(parsed, 'competitor');
-  const audiences = getOptions(parsed, 'audience');
-  const count = parseIntegerOption(parsed, 'count', { min: 5, max: 30 });
+const getCommand = defineCommand({
+  id: 'keywords.get',
+  summary: 'Get one keyword by id.',
+  kind: CommandKind.READ,
+  toolsets: TOOLSETS,
+  input: { keywordId: uuid().required(), kind: string() },
+  cli: KEYWORD_ID_CLI,
+  run: (input, ctx) =>
+    ctx.http({
+      method: 'GET',
+      path: KEYWORD_PATH,
+      pathParams: { keywordId: input.keywordId },
+      query: { kind: input.kind },
+    }),
+});
 
-  if (count === undefined) {
-    throw Object.assign(new Error('Missing required option: --count <n>.'), {
-      cliCode: 'CLI_INVALID_USAGE',
-      guidance:
-        'Ask the human how many keywords to generate first. The dashboard-equivalent flow allows 5-30 keywords when enough scheduler slots are free. Use `outrank-cli keywords generation-status --product <product-id>` to inspect current slot capacity.',
-    });
-  }
+const exportCommand = defineCommand({
+  id: 'keywords.export',
+  summary: 'Export the keyword plan for a product.',
+  kind: CommandKind.READ,
+  toolsets: TOOLSETS,
+  input: { productId: productOption() },
+  cli: productCli,
+  run: (input, ctx) => ctx.http({ method: 'GET', path: '/keywords/export', query: { product_id: input.productId } }),
+});
 
-  const body = {
-    product_id: getRequiredProductOption(parsed),
-    keywords_count: count,
-    filters: {
-      isGenerateByCompetitors: source === 'competitors' || source === 'both',
-      isGenerateByAudiences: source === 'audiences' || source === 'both',
-      ...(competitors.length > 0 ? { competitors } : {}),
-      ...(audiences.length > 0 ? { target_audiences: audiences } : {}),
-    },
-  };
-
-  const response = await requestAgentApi(parsed, {
-    method: 'POST',
-    path: '/keywords/generate',
-    body,
-  });
-  return response.payload;
-};
+const generationStatusCommand = defineCommand({
+  id: 'keywords.generation-status',
+  summary: 'Show keyword generation status and scheduler slot capacity for a product.',
+  kind: CommandKind.READ,
+  toolsets: TOOLSETS,
+  input: { productId: productOption() },
+  cli: productCli,
+  run: (input, ctx) =>
+    ctx.http({ method: 'GET', path: '/keywords/generation-status', query: { product_id: input.productId } }),
+});
 
-const handleKeywordsBulkProcess = async (parsed) => {
-  const body = await readJsonInput(parsed);
-  body.product_id = getRequiredProductOption(parsed);
+const addCommand = defineCommand({
+  id: 'keywords.add',
+  summary: 'Add a keyword to a product from a JSON body.',
+  kind: CommandKind.WRITE,
+  toolsets: TOOLSETS,
+  input: { productId: productOption() },
+  cli: productCli,
+  body: BodyMode.JSON,
+  bodyMerge: { product_id: 'productId' },
+  run: (input, ctx) => ctx.http({ method: 'POST', path: '/keywords', body: input.body }),
+});
 
-  const keywordRegion = getOption(parsed, 'keyword-region');
-  if (keywordRegion) {
-    body.keyword_region = keywordRegion;
-  }
+const updateCommand = defineCommand({
+  id: 'keywords.update',
+  summary: 'Update a keyword (instructions, schedule, quality questions) from a JSON body.',
+  kind: CommandKind.WRITE,
+  toolsets: TOOLSETS,
+  input: { keywordId: uuid().required() },
+  cli: KEYWORD_ID_CLI,
+  body: BodyMode.JSON,
+  run: (input, ctx) =>
+    ctx.http({ method: 'PATCH', path: KEYWORD_PATH, pathParams: { keywordId: input.keywordId }, body: input.body }),
+});
 
-  const response = await requestAgentApi(parsed, {
-    method: 'POST',
-    path: '/keywords/bulk-process',
-    body,
-  });
-  return response.payload;
-};
-
-const handleKeywordsBulkReschedule = async (parsed) => {
-  const body = await readJsonInput(parsed);
-  const response = await requestAgentApi(parsed, {
-    method: 'POST',
-    path: '/keywords/bulk-reschedule',
-    body,
-  });
-  return response.payload;
-};
+const suggestCommand = defineCommand({
+  id: 'keywords.suggest',
+  summary: 'Suggest keywords for a product from a seed keyword or a theme.',
+  kind: CommandKind.READ,
+  toolsets: TOOLSETS,
+  input: {
+    keyword: string(),
+    theme: string(),
+    productId: productOption(),
+    keywordRegion: string(),
+    limit: int({ min: LIST_MIN_LIMIT, max: KEYWORDS_SUGGEST_MAX_LIMIT }),
+  },
+  cli: productCli,
+  refine: (input, ctx) => {
+    if (input.keyword || input.theme) return;
+    if (ctx.surface === Surface.MCP) {
+      throw usageError('Missing required argument: keyword or theme.', MCP_USAGE_GUIDANCE);
+    }
+    throw usageError('Missing required option: --keyword <text> or --theme <text>.', SUGGEST_TERM_GUIDANCE);
+  },
+  run: (input, ctx) =>
+    ctx.http({
+      method: 'POST',
+      path: '/keywords/suggest',
+      body: {
+        product_id: input.productId,
+        ...(input.keyword ? { keyword: input.keyword } : {}),
+        ...(input.theme ? { theme: input.theme } : {}),
+        ...(input.keywordRegion ? { keyword_region: input.keywordRegion } : {}),
+        ...(input.limit !== undefined ? { limit: input.limit } : {}),
+      },
+    }),
+});
 
-const handleKeywordsDelete = async (parsed) => {
-  const keywordId = getRequiredPositional(parsed, 0, '<keyword-id>');
-  const response = await requestAgentApi(parsed, {
-    method: 'DELETE',
-    path: `/keywords/${keywordId}`,
-  });
-  return response.payload;
-};
+const generateCommand = defineCommand({
+  id: 'keywords.generate',
+  summary: 'Generate keywords for a product from competitors and/or target audiences.',
+  kind: CommandKind.WRITE,
+  toolsets: TOOLSETS,
+  input: {
+    source: oneOf(GENERATE_SOURCES).default(GenerateSource.BOTH).guidance(SOURCE_GUIDANCE),
+    count: int({ min: KEYWORDS_GENERATE_MIN_COUNT, max: KEYWORDS_GENERATE_MAX_COUNT }).required(COUNT_REQUIRED),
+    competitors: list({ split: null }),
+    audiences: list({ split: null }),
+    productId: productOption(),
+  },
+  cli: {
+    options: { product: 'productId', competitor: 'competitors', audience: 'audiences' },
+    placeholders: { productId: '<product-id>', count: '<n>' },
+    rejectedOptions: { theme: LEGACY_GENERATE_OPTION, country: LEGACY_GENERATE_OPTION },
+  },
+  longRunning: { pollTool: 'keywords.generation-status' },
+  run: (input, ctx) =>
+    ctx.http({
+      method: 'POST',
+      path: '/keywords/generate',
+      body: {
+        product_id: input.productId,
+        keywords_count: input.count,
+        filters: {
+          isGenerateByCompetitors: input.source !== GenerateSource.AUDIENCES,
+          isGenerateByAudiences: input.source !== GenerateSource.COMPETITORS,
+          ...(input.competitors?.length ? { competitors: input.competitors } : {}),
+          ...(input.audiences?.length ? { target_audiences: input.audiences } : {}),
+        },
+      },
+    }),
+});
 
-const handleKeywordsBulkDelete = async (parsed) => {
-  const body = await readJsonInput(parsed);
-  const response = await requestAgentApi(parsed, {
-    method: 'POST',
-    path: '/keywords/bulk-delete',
-    body,
-  });
-  return response.payload;
-};
+const bulkProcessCommand = defineCommand({
+  id: 'keywords.bulk-process',
+  summary: 'Bulk-process a list of keywords for a product from a JSON body.',
+  kind: CommandKind.READ,
+  toolsets: TOOLSETS,
+  input: { productId: productOption(), keywordRegion: string() },
+  cli: productCli,
+  body: BodyMode.JSON,
+  bodyMerge: { product_id: 'productId', keyword_region: 'keywordRegion' },
+  run: (input, ctx) => ctx.http({ method: 'POST', path: '/keywords/bulk-process', body: input.body }),
+});
 
-export const handleKeywordsCommand = async (argv) => {
-  const subcommand = argv[0];
-  const parsed = parseArgs(argv.slice(1));
-  const wantsHelp = !subcommand || subcommand === '--help' || subcommand === '-h' || subcommand === 'help' || hasFlag(parsed, 'help');
+const bulkRescheduleCommand = defineCommand({
+  id: 'keywords.bulk-reschedule',
+  summary: 'Reschedule several keywords from a JSON body.',
+  kind: CommandKind.WRITE,
+  toolsets: TOOLSETS,
+  body: BodyMode.JSON,
+  run: (input, ctx) => ctx.http({ method: 'POST', path: '/keywords/bulk-reschedule', body: input.body }),
+});
 
-  if (wantsHelp) {
-    return cliSuccess(
-      {
-        usage: KEYWORDS_HELP.trim(),
-      },
-      'Choose one of: list, get, export, generation-status, add, update, suggest, generate, bulk-process, bulk-reschedule, delete, bulk-delete.',
-    );
-  }
+const deleteCommand = defineCommand({
+  id: 'keywords.delete',
+  summary: 'Delete one keyword.',
+  kind: CommandKind.DESTRUCTIVE,
+  toolsets: TOOLSETS,
+  input: { keywordId: uuid().required() },
+  cli: KEYWORD_ID_CLI,
+  run: (input, ctx) => ctx.http({ method: 'DELETE', path: KEYWORD_PATH, pathParams: { keywordId: input.keywordId } }),
+});
 
-  if (subcommand === 'list') return handleKeywordsList(parsed);
-  if (subcommand === 'get') return handleKeywordsGet(parsed);
-  if (subcommand === 'export') return handleKeywordsExport(parsed);
-  if (subcommand === 'generation-status') return handleKeywordsGenerationStatus(parsed);
-  if (subcommand === 'add') return handleKeywordsAdd(parsed);
-  if (subcommand === 'update') return handleKeywordsUpdate(parsed);
-  if (subcommand === 'suggest') return handleKeywordsSuggest(parsed);
-  if (subcommand === 'generate') return handleKeywordsGenerate(parsed);
-  if (subcommand === 'bulk-process') return handleKeywordsBulkProcess(parsed);
-  if (subcommand === 'bulk-reschedule') return handleKeywordsBulkReschedule(parsed);
-  if (subcommand === 'delete') return handleKeywordsDelete(parsed);
-  if (subcommand === 'bulk-delete') return handleKeywordsBulkDelete(parsed);
+const bulkDeleteCommand = defineCommand({
+  id: 'keywords.bulk-delete',
+  summary: 'Delete several keywords from a JSON body of ids.',
+  kind: CommandKind.DESTRUCTIVE,
+  toolsets: TOOLSETS,
+  body: BodyMode.JSON,
+  run: (input, ctx) => ctx.http({ method: 'POST', path: '/keywords/bulk-delete', body: input.body }),
+});
 
-  throw Object.assign(new Error(`Unknown keywords subcommand: ${subcommand}.`), {
-    cliCode: 'CLI_INVALID_USAGE',
+export const keywordsGroup = defineGroup({
+  id: 'keywords',
+  help: {
+    usage: KEYWORDS_HELP,
+    guidance:
+      'Choose one of: list, get, export, generation-status, add, update, suggest, generate, bulk-process, ' +
+      'bulk-reschedule, delete, bulk-delete.',
+  },
+  unknown: (word) => ({
+    message: `Unknown keywords subcommand: ${word}.`,
     guidance: 'Run `outrank-cli keywords --help` to see available keyword commands.',
-  });
-};
+  }),
+  children: [
+    listCommand,
+    getCommand,
+    exportCommand,
+    generationStatusCommand,
+    addCommand,
+    updateCommand,
+    suggestCommand,
+    generateCommand,
+    bulkProcessCommand,
+    bulkRescheduleCommand,
+    deleteCommand,
+    bulkDeleteCommand,
+  ],
+});