outrank-cli 0.6.0 → 0.7.0

package/src/commands/products/core.js

@@ -1,10 +1,82 @@
 import { LIST_MAX_LIMIT, LIST_MIN_LIMIT } from '../../core/constants.js';
-import { int, string } from '../../core/schema.js';
+import { bool, int, list, object, string } from '../../core/schema.js';
 import { BodyMode, CommandKind, Toolset, defineCommand, defineGroup } from '../registry.js';
 import { PRODUCT_CLI, productInput, productParams } from './shared.js';
 
 const TOOLSETS = [Toolset.CORE];
 const PRODUCT_PATH = '/products/{productId}';
+const PRODUCT_NAME_HINT = '2-50 characters.';
+const PRODUCT_DESCRIPTION_HINT = '50-8000 characters.';
+const TARGET_AUDIENCES_HINT = '3-7 audience texts of at most 200 characters each; replaces the list.';
+const HTTP_URL_HINT = 'http(s) URL.';
+const SITEMAP_URL_HINT = 'http(s) URL ending in .xml.';
+const EXAMPLE_ARTICLE_URLS_HINT = 'At most 3 http(s) URLs.';
+const KEYWORD_REGION_HINT = 'Country code such as us, uk or global-us.';
+const COMPETITORS_HINT = '3-7 competitors.';
+
+const PRODUCT_CREATE_REQUIRED = {
+  guidance:
+    'Creating a product needs every field: name, url, description, target_audiences (3-7), language, ' +
+    'keyword_region and competitors (3-7 of { name, link }). Agree them with the user, then call again.',
+};
+const COMPETITOR_REQUIRED = { guidance: 'Each competitor needs a name and a link.' };
+
+const competitorShape = () =>
+  object().shape({
+    name: string().required(COMPETITOR_REQUIRED),
+    link: string().required(COMPETITOR_REQUIRED).describe(HTTP_URL_HINT),
+  });
+
+const PRODUCT_CREATE_BODY = object().shape({
+  name: string().required(PRODUCT_CREATE_REQUIRED).describe(PRODUCT_NAME_HINT),
+  url: string().required(PRODUCT_CREATE_REQUIRED).describe(HTTP_URL_HINT),
+  description: string().required(PRODUCT_CREATE_REQUIRED).describe(PRODUCT_DESCRIPTION_HINT),
+  target_audiences: list().required(PRODUCT_CREATE_REQUIRED).describe(TARGET_AUDIENCES_HINT),
+  language: string().required(PRODUCT_CREATE_REQUIRED),
+  keyword_region: string().required(PRODUCT_CREATE_REQUIRED).describe(KEYWORD_REGION_HINT),
+  competitors: list({ item: competitorShape() }).required(PRODUCT_CREATE_REQUIRED).describe(COMPETITORS_HINT),
+});
+
+const PRODUCT_UPDATE_BODY = object().shape({
+  name: string().describe(PRODUCT_NAME_HINT),
+  description: string().describe(PRODUCT_DESCRIPTION_HINT),
+  target_audiences: list().describe(TARGET_AUDIENCES_HINT),
+  sitemap_url: string().describe(SITEMAP_URL_HINT),
+  blog_root_url: string().describe(HTTP_URL_HINT),
+  example_article_urls: list().describe(EXAMPLE_ARTICLE_URLS_HINT),
+  auto_keyword_generation_disabled: bool(),
+});
+
+const OUTPUT_SETTINGS_OPTION_HINT = 'Allowed values are in products_output_settings_get data._meta.';
+const OUTPUT_SETTINGS_INTERNAL_LINKS_MIN = 0;
+const OUTPUT_SETTINGS_INTERNAL_LINKS_MAX = 5;
+const BRAND_COLOR_HINT = '6-digit hex color such as #1A2B3C.';
+const GLOBAL_ARTICLE_PROMPT_HINT = 'At most 10000 characters; null clears it.';
+const GLOBAL_KEYWORD_PROMPT_HINT = 'At most 2000 characters; null clears it.';
+
+const OUTPUT_SETTINGS_UPDATE_BODY = object().shape({
+  language: string(),
+  keyword_region: string().describe(KEYWORD_REGION_HINT),
+  tone_and_style: string().describe(OUTPUT_SETTINGS_OPTION_HINT),
+  image_style: string().describe(OUTPUT_SETTINGS_OPTION_HINT),
+  featured_image_style: string().describe(OUTPUT_SETTINGS_OPTION_HINT),
+  global_article_prompt: string().nullable().describe(GLOBAL_ARTICLE_PROMPT_HINT),
+  global_keyword_prompt: string().nullable().describe(GLOBAL_KEYWORD_PROMPT_HINT),
+  outline: string().nullable(),
+  outrank_prompt: string().nullable(),
+  not_included_words: string().nullable(),
+  internal_links: int({ min: OUTPUT_SETTINGS_INTERNAL_LINKS_MIN, max: OUTPUT_SETTINGS_INTERNAL_LINKS_MAX }),
+  brand_color: string().describe(BRAND_COLOR_HINT),
+  auto_publish: bool(),
+  table_of_contents: bool(),
+  is_cta_included: bool(),
+  is_video_included: bool(),
+  mention_similar_products: bool(),
+  is_infographics_enabled: bool(),
+  is_first_person_enabled: bool(),
+  are_in_article_emojis_disabled: bool(),
+  use_different_featured_style: bool(),
+});
 
 export const productsList = defineCommand({
   id: 'products.list',
@@ -36,6 +108,7 @@ export const productsCreate = defineCommand({
   kind: CommandKind.WRITE,
   toolsets: TOOLSETS,
   body: BodyMode.JSON,
+  bodyField: PRODUCT_CREATE_BODY,
   run: (input, ctx) => ctx.http({ method: 'POST', path: '/products', body: input.body }),
 });
 
@@ -47,6 +120,7 @@ export const productsUpdate = defineCommand({
   input: productInput(),
   cli: PRODUCT_CLI,
   body: BodyMode.JSON,
+  bodyField: PRODUCT_UPDATE_BODY,
   run: (input, ctx) =>
     ctx.http({ method: 'PATCH', path: PRODUCT_PATH, pathParams: productParams(input), body: input.body }),
 });
@@ -72,7 +146,17 @@ export const productsResume = defineCommand({
     ctx.http({ method: 'POST', path: `${PRODUCT_PATH}/resume`, pathParams: productParams(input) }),
 });
 
-const settingsPair = ({ id, noun, resource, getSummary, replaceSummary, replaceMethod, replaceKind, guidance }) =>
+const settingsPair = ({
+  id,
+  noun,
+  resource,
+  getSummary,
+  replaceSummary,
+  replaceMethod,
+  replaceKind,
+  replaceBody,
+  guidance,
+}) =>
   defineGroup({
     id: `products.${id}`,
     help: {
@@ -104,6 +188,7 @@ const settingsPair = ({ id, noun, resource, getSummary, replaceSummary, replaceM
         input: productInput(),
         cli: PRODUCT_CLI,
         body: BodyMode.JSON,
+        ...(replaceBody ? { bodyField: replaceBody } : {}),
         run: (input, ctx) =>
           ctx.http({
             method: replaceMethod,
@@ -123,6 +208,7 @@ export const outputSettingsGroup = settingsPair({
   replaceSummary: 'Patch the article output settings of a product from a JSON body.',
   replaceMethod: 'PATCH',
   replaceKind: CommandKind.WRITE,
+  replaceBody: OUTPUT_SETTINGS_UPDATE_BODY,
   guidance: 'Use `get` to inspect current article settings and `update` to patch them.',
 });
 

package/src/commands/products/integrations.js

@@ -63,7 +63,7 @@ const FRAMER_GUIDANCE =
 const TOOLSETS = [Toolset.INTEGRATIONS];
 const NOTION_ID_PATTERN = /^[A-Za-z0-9-]{1,64}$/;
 const NOTION_ID_GUIDANCE = 'Use a database id returned by the Notion databases command.';
-const PROVIDERS = Object.freeze([
+export const PROVIDERS = Object.freeze([
   'wordpress-plugin',
   'wordpress-com',
   'notion',
@@ -72,8 +72,20 @@ const PROVIDERS = Object.freeze([
   'shopify',
   'wix',
   'webhook',
+  'ghost',
   'nextjs-blog',
 ]);
+export const PREPARE_PROVIDERS = Object.freeze(['wordpress-plugin']);
+export const CONNECT_PROVIDERS = Object.freeze(['wordpress-com', 'notion']);
+export const VALIDATE_PROVIDERS = Object.freeze([
+  'webhook',
+  'ghost',
+  'shopify',
+  'wix',
+  'framer',
+  'wordpress-plugin',
+  'webflow',
+]);
 const WEBFLOW_RESOURCES = Object.freeze(['sites', 'collections', 'fields', 'items']);
 const FRAMER_RESOURCES = Object.freeze(['collections', 'fields']);
 const INTEGRATION_PATH = '/products/{productId}/integrations/{integrationId}';
@@ -88,7 +100,7 @@ const ATTEMPT_ID_REQUIRED = {
 };
 const SENSITIVE_BODY = { sensitiveBody: true };
 
-const providerInput = () => ({ provider: oneOf(PROVIDERS).required(), ...productInput() });
+const providerInput = (providers) => ({ provider: oneOf(providers).required(), ...productInput() });
 const providerParams = (input) => ({ productId: input.productId, provider: input.provider });
 const integrationInput = () => ({ ...productInput(), integrationId: uuid().required() });
 const integrationParams = (input) => ({ productId: input.productId, integrationId: input.integrationId });
@@ -106,7 +118,7 @@ const prepare = defineCommand({
   summary: 'Prepare a provider integration for a product (e.g. generate the WordPress plugin token).',
   kind: CommandKind.WRITE,
   toolsets: TOOLSETS,
-  input: providerInput(),
+  input: providerInput(PREPARE_PROVIDERS),
   cli: PROVIDER_PRODUCT_CLI,
   body: BodyMode.OPTIONAL_JSON,
   run: (input, ctx) =>
@@ -123,7 +135,7 @@ const connect = defineCommand({
   summary: 'Start an OAuth connect flow for a provider and return the connect URL.',
   kind: CommandKind.WRITE,
   toolsets: TOOLSETS,
-  input: providerInput(),
+  input: providerInput(CONNECT_PROVIDERS),
   cli: PROVIDER_PRODUCT_CLI,
   body: BodyMode.OPTIONAL_JSON,
   run: (input, ctx) =>
@@ -135,7 +147,7 @@ const poll = defineCommand({
   summary: 'Poll an OAuth connect attempt until the handoff completes.',
   kind: CommandKind.READ,
   toolsets: TOOLSETS,
-  input: { ...providerInput(), attemptId: string().required(ATTEMPT_ID_REQUIRED) },
+  input: { ...providerInput(CONNECT_PROVIDERS), attemptId: string().required(ATTEMPT_ID_REQUIRED) },
   cli: { ...PROVIDER_PRODUCT_CLI, placeholders: ATTEMPT_ID_PLACEHOLDERS },
   run: (input, ctx) =>
     ctx.http({
@@ -210,7 +222,7 @@ const validate = defineCommand({
   summary: 'Validate provider credentials from a JSON body without saving them.',
   kind: CommandKind.READ,
   toolsets: TOOLSETS,
-  input: { provider: oneOf(PROVIDERS).required() },
+  input: { provider: oneOf(VALIDATE_PROVIDERS).required() },
   cli: { positionals: ['provider'] },
   mcp: SENSITIVE_BODY,
   body: BodyMode.JSON,

package/src/commands/registry.js

@@ -44,7 +44,9 @@ export const NodeType = Object.freeze({
 });
 
 export const BODY_INPUT_NAME = 'body';
-const MCP_FLAG_NAMES = Object.freeze(['sensitiveBody', 'untrustedOutput', 'redact']);
+const MCP_FLAG_NAMES = Object.freeze(['sensitiveBody', 'untrustedOutput', 'untrustedFields', 'untrustedWhen', 'redact']);
+const FIELD_NAME_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+const FIELD_PATH_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*(?:\[\])?(?:\.[a-zA-Z_][a-zA-Z0-9_]*(?:\[\])?)*$/;
 const ID_PATTERN = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)*$/;
 const NO_RESULT_GUIDANCE = 'This is a CLI bug: the command finished without producing a result. Report the command.';
 
@@ -124,6 +126,25 @@ export const defineGroup = ({ id, help, unknown, children, description, command
   ...(command ? { ...normalizeCommand({ ...command, id }), type: NodeType.GROUP, help, children } : {}),
 });
 
+const assertUntrustedWhen = (node, paths) => {
+  const when = node.mcp.untrustedWhen;
+  if (when === undefined) return;
+  const shapeOk =
+    Boolean(when) &&
+    typeof when === 'object' &&
+    typeof when.record === 'string' &&
+    (when.record === '' || FIELD_PATH_PATTERN.test(when.record)) &&
+    typeof when.flag === 'string' &&
+    FIELD_NAME_PATTERN.test(when.flag);
+  if (!shapeOk) {
+    throw registryError(`${node.id}: mcp.untrustedWhen must be { record: '<path or empty>', flag: '<field name>' }`);
+  }
+  const prefix = when.record ? `${when.record}.` : '';
+  if (!paths.every((entry) => entry.startsWith(prefix) && entry.length > prefix.length)) {
+    throw registryError(`${node.id}: every mcp.untrustedFields path must sit inside the untrustedWhen record`);
+  }
+};
+
 const assertMcpShape = (node) => {
   if (node.mcp === true || node.mcp === false) return;
   if (!node.mcp || typeof node.mcp !== 'object') throw registryError(`${node.id}: mcp must be a boolean or an object`);
@@ -133,6 +154,20 @@ const assertMcpShape = (node) => {
   if (node.mcp.redact !== undefined && !Array.isArray(node.mcp.redact)) {
     throw registryError(`${node.id}: mcp.redact must be an array of field names`);
   }
+  if (node.mcp.untrustedFields === undefined) {
+    if (node.mcp.untrustedWhen !== undefined) {
+      throw registryError(`${node.id}: mcp.untrustedWhen requires mcp.untrustedFields`);
+    }
+    return;
+  }
+  const paths = node.mcp.untrustedFields;
+  if (!Array.isArray(paths) || paths.length === 0 || !paths.every((entry) => FIELD_PATH_PATTERN.test(entry))) {
+    throw registryError(`${node.id}: mcp.untrustedFields must be a non-empty array of field paths`);
+  }
+  if (node.mcp.untrustedOutput !== true) {
+    throw registryError(`${node.id}: mcp.untrustedFields requires untrustedOutput: true`);
+  }
+  assertUntrustedWhen(node, paths);
 };
 
 const assertCliShape = (node) => {

package/src/core/context.js

@@ -268,7 +268,7 @@ const renderCliReference = (spec, args) => {
 
 const toSnakeCase = (name) => name.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
 
-const renderMcpReference = (spec, args) => {
+export const renderMcpReference = (spec, args) => {
   const toolName = spec.id.replaceAll('.', '_').replaceAll('-', '_');
   const entries = Object.entries(args).filter(([, value]) => value !== undefined);
   if (entries.length === 0) return toolName;

package/src/core/http.js

@@ -21,6 +21,7 @@ const FORBIDDEN_PATH_SEGMENTS = new Set(['.', '..', '']);
 const TIMEOUT_ERROR_NAME = 'TimeoutError';
 const TIMEOUT_ABORT_MESSAGE = 'The request timed out.';
 const READ_METHOD = 'GET';
+export const RECEIVED_RESPONSE_PROPERTY = 'receivedResponse';
 const RESPONSE_TIMEOUT_CODES = new Set(['UND_ERR_HEADERS_TIMEOUT', 'UND_ERR_BODY_TIMEOUT']);
 const NEVER_SENT_CODES = new Set([
   'ENOTFOUND',
@@ -376,18 +377,15 @@ export const requestAgentApi = async (
     throw failure(error);
   }
 
+  const received = { status: response.status, headers: Object.fromEntries(response.headers.entries()) };
   let rawBody;
   try {
     rawBody = await response.text();
   } catch (error) {
-    throw failure(error);
+    throw Object.assign(failure(error), { [RECEIVED_RESPONSE_PROPERTY]: received });
   } finally {
     abort.release();
   }
 
-  return {
-    result: interpretResponse({ response, url, baseUrl: ctx.baseUrl, rawBody }),
-    status: response.status,
-    headers: Object.fromEntries(response.headers.entries()),
-  };
+  return { result: interpretResponse({ response, url, baseUrl: ctx.baseUrl, rawBody }), ...received };
 };

package/src/core/schema.js

@@ -4,6 +4,7 @@ export const FieldKind = Object.freeze({
   STRING: 'string',
   UUID: 'uuid',
   INT: 'int',
+  NUMBER: 'number',
   BOOL: 'bool',
   ENUM: 'enum',
   LIST: 'list',
@@ -46,17 +47,20 @@ const createField = (kind, options = {}) => {
   field.describe = (description) => derive({ description });
   field.default = (defaultValue) => derive({ defaultValue });
   field.guidance = (invalidGuidance) => derive({ invalidGuidance });
+  field.nullable = () => derive({ isNullable: true });
+  if (kind === FieldKind.OBJECT) field.shape = (properties) => derive({ properties: Object.freeze({ ...properties }) });
   return field;
 };
 
 export const string = () => createField(FieldKind.STRING);
 export const uuid = () => createField(FieldKind.UUID);
 export const int = ({ min, max } = {}) => createField(FieldKind.INT, { min, max });
+export const number = ({ min, max } = {}) => createField(FieldKind.NUMBER, { min, max });
 export const bool = ({ serialize = BoolSerialize.OMIT_FALSE } = {}) => createField(FieldKind.BOOL, { serialize });
 export const oneOf = (values) => createField(FieldKind.ENUM, { values: Object.freeze([...values]) });
 export const list = ({ split = DEFAULT_LIST_SEPARATOR, serialize = ListSerialize.ARRAY, item = string() } = {}) =>
   createField(FieldKind.LIST, { split, serialize, item });
-export const object = () => createField(FieldKind.OBJECT);
+export const object = () => createField(FieldKind.OBJECT, { properties: undefined });
 export const json = () => createField(FieldKind.JSON);
 export const image = () => createField(FieldKind.IMAGE);
 
@@ -92,6 +96,12 @@ const parseScalar = (field, value, label) => {
     if (field.max !== undefined && number > field.max) throw usageError(`${label} must be <= ${field.max}.`);
     return number;
   }
+  if (field.kind === FieldKind.NUMBER) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) throw usageError(`${label} must be a number.`);
+    if (field.min !== undefined && value < field.min) throw usageError(`${label} must be >= ${field.min}.`);
+    if (field.max !== undefined && value > field.max) throw usageError(`${label} must be <= ${field.max}.`);
+    return value;
+  }
   if (field.kind === FieldKind.BOOL) {
     if (typeof value === 'boolean') return value;
     if (value === TRUE_TEXT) return true;
@@ -104,7 +114,7 @@ const parseScalar = (field, value, label) => {
   }
   if (field.kind === FieldKind.OBJECT) {
     if (!isPlainObject(value)) throw usageError(`${label} must be a JSON object.`);
-    return value;
+    return field.properties ? parseShapedObject(field, value, label) : value;
   }
   if (field.kind === FieldKind.JSON) {
     return value;
@@ -148,6 +158,37 @@ export const parseFieldValue = (field, value, label, { splitLists = true } = {})
     return parseScalar(field, value, label);
   });
 
+const missingPropertyError = (property, label) => {
+  const guidance = property.requiredError?.guidance ?? property.invalidGuidance;
+  return usageError(property.requiredError?.message ?? `Missing required field: ${label}.`, guidance);
+};
+
+const parsePropertyValue = (property, value, label) =>
+  withFieldGuidance(property, () => {
+    if (property.kind !== FieldKind.LIST) return parseScalar(property, value, label);
+    if (!Array.isArray(value)) throw usageError(`${label} must be an array.`);
+    const items = parseList(property, value, label, false);
+    if (property.isRequired && items.length === 0) throw missingPropertyError(property, label);
+    return items;
+  });
+
+const parseShapedObject = (field, value, label) => {
+  const parsed = { ...value };
+  for (const [key, property] of Object.entries(field.properties)) {
+    const propertyLabel = `${label}.${key}`;
+    if (value[key] === undefined || (value[key] === null && property.isNullable)) {
+      if (property.isRequired && value[key] === undefined) throw missingPropertyError(property, propertyLabel);
+      continue;
+    }
+    if (value[key] === null) {
+      if (property.isRequired) throw missingPropertyError(property, propertyLabel);
+      throw usageError(`${propertyLabel} must not be null.`);
+    }
+    parsed[key] = parsePropertyValue(property, value[key], propertyLabel);
+  }
+  return parsed;
+};
+
 const missingFieldError = (field, name, missingMessage) => {
   const message = field.requiredError?.message ?? missingMessage(name);
   return usageError(message, field.requiredError?.guidance);
@@ -185,18 +226,30 @@ export const serializeList = (field, value) => {
   return value;
 };
 
-const zodScalar = (z, field, { jsonAsObject = false } = {}) => {
-  if (field.kind === FieldKind.STRING) return z.string().min(1);
+const boundedNumber = (schema, field) => {
+  let bounded = schema;
+  if (field.min !== undefined) bounded = bounded.min(field.min);
+  if (field.max !== undefined) bounded = bounded.max(field.max);
+  return bounded;
+};
+
+const zodScalar = (z, field, options = {}) => {
+  const { jsonAsObject = false, inBody = false } = options;
+  if (field.kind === FieldKind.STRING) return inBody ? z.string() : z.string().min(1);
   if (field.kind === FieldKind.UUID) return z.string().regex(UUID_PATTERN, UUID_MESSAGE);
-  if (field.kind === FieldKind.INT) {
-    let schema = z.number().int();
-    if (field.min !== undefined) schema = schema.min(field.min);
-    if (field.max !== undefined) schema = schema.max(field.max);
-    return schema;
-  }
+  if (field.kind === FieldKind.INT) return boundedNumber(z.number().int(), field);
+  if (field.kind === FieldKind.NUMBER) return boundedNumber(z.number(), field);
   if (field.kind === FieldKind.BOOL) return z.boolean();
   if (field.kind === FieldKind.ENUM) return z.enum(field.values);
-  if (field.kind === FieldKind.OBJECT) return z.object({}).passthrough();
+  if (field.kind === FieldKind.OBJECT) {
+    if (!field.properties) return z.object({}).passthrough();
+    const propertyOptions = { ...options, inBody: true, jsonAsObject: false };
+    const entries = Object.entries(field.properties).map(([key, property]) => [
+      key,
+      zodField(z, property, propertyOptions),
+    ]);
+    return z.object(Object.fromEntries(entries)).passthrough();
+  }
   if (field.kind === FieldKind.JSON) return jsonAsObject ? z.object({}).passthrough() : z.unknown();
   if (field.kind === FieldKind.IMAGE) {
     return z.object({ file_base64: z.string().min(1), file_name: z.string().min(1), file_type: z.string().min(1) });
@@ -204,13 +257,19 @@ const zodScalar = (z, field, { jsonAsObject = false } = {}) => {
   throw new Error(`Unknown field kind: ${field.kind}`);
 };
 
-export const zodField = (z, field, { jsonAsObject = false, description = field.description } = {}) => {
+const zodListItem = (z, item, options) =>
+  item.kind === FieldKind.STRING
+    ? z.string().trim().min(1)
+    : zodScalar(z, item, { ...options, inBody: false, jsonAsObject: false });
+
+export const zodField = (z, field, { jsonAsObject = false, inBody = false, description = field.description } = {}) => {
   const minItems = field.isRequired ? 1 : 0;
-  const options = { jsonAsObject };
+  const options = { jsonAsObject, inBody };
   let schema =
     field.kind === FieldKind.LIST
-      ? z.array(zodScalar(z, field.item, options)).min(minItems)
+      ? z.array(zodListItem(z, field.item, options)).min(minItems)
       : zodScalar(z, field, options);
+  if (field.isNullable) schema = schema.nullable();
   if (description) schema = schema.describe(description);
   return field.isRequired ? schema : schema.optional();
 };