outrank-cli 0.5.0 → 0.6.0

package/src/commands/products/linking.js

@@ -0,0 +1,192 @@
+import { uuid } from '../../core/schema.js';
+import { BodyMode, CommandKind, Toolset, defineCommand, defineGroup } from '../registry.js';
+import { PRODUCT_CLI, productInput, productParams, withProduct } from './shared.js';
+
+const LINKING_USAGE = `Usage:
+  outrank-cli products linking sources get <product-id>
+  outrank-cli products linking sources update <product-id> --json <object>
+  outrank-cli products linking detect <product-id>
+  outrank-cli products linking target-config get <product-id>
+  outrank-cli products linking target-config update <product-id> --json <object>
+  outrank-cli products linking targets list <product-id>
+  outrank-cli products linking targets add-manual <product-id> --json <object>
+  outrank-cli products linking targets upsert <product-id> --json <object>
+  outrank-cli products linking targets clear-customizations <product-id> <target-id>
+  outrank-cli products linking targets delete <product-id> <target-id>`;
+
+const SOURCES_USAGE =
+  'Usage:\n  outrank-cli products linking sources get <product-id>\n' +
+  '  outrank-cli products linking sources update <product-id> --json <object>';
+const TARGET_CONFIG_USAGE =
+  'Usage:\n  outrank-cli products linking target-config get <product-id>\n' +
+  '  outrank-cli products linking target-config update <product-id> --json <object>';
+const TARGETS_USAGE = `Usage:
+  outrank-cli products linking targets list <product-id>
+  outrank-cli products linking targets add-manual <product-id> --json <object>
+  outrank-cli products linking targets upsert <product-id> --json <object>
+  outrank-cli products linking targets clear-customizations <product-id> <target-id>
+  outrank-cli products linking targets delete <product-id> <target-id>`;
+
+const TOOLSETS = [Toolset.LINKING];
+const LINKING_PATH = '/products/{productId}/linking';
+const TARGET_PATH = `${LINKING_PATH}/targets/{targetId}`;
+const TARGET_CLI = withProduct(['targetId']);
+
+const targetInput = () => ({ ...productInput(), targetId: uuid().required() });
+const targetParams = (input) => ({ productId: input.productId, targetId: input.targetId });
+
+const getAndSet = ({ id, resource, method, updateSummary, getSummary, usage, guidance, unknownNoun, aliases }) =>
+  defineGroup({
+    id: `products.linking.${id}`,
+    help: { usage, guidance },
+    unknown: (word) => ({
+      message: `Unknown products linking ${id} subcommand: ${word}.`,
+      guidance: `Run \`outrank-cli products linking ${id} --help\` to see available ${unknownNoun} commands.`,
+    }),
+    children: [
+      defineCommand({
+        id: `products.linking.${id}.get`,
+        summary: getSummary,
+        kind: CommandKind.READ,
+        toolsets: TOOLSETS,
+        input: productInput(),
+        cli: PRODUCT_CLI,
+        run: (input, ctx) =>
+          ctx.http({ method: 'GET', path: `${LINKING_PATH}/${resource}`, pathParams: productParams(input) }),
+      }),
+      defineCommand({
+        id: `products.linking.${id}.update`,
+        summary: updateSummary,
+        kind: CommandKind.WRITE,
+        toolsets: TOOLSETS,
+        input: productInput(),
+        cli: { ...PRODUCT_CLI, aliases },
+        body: BodyMode.JSON,
+        run: (input, ctx) =>
+          ctx.http({ method, path: `${LINKING_PATH}/${resource}`, pathParams: productParams(input), body: input.body }),
+      }),
+    ],
+  });
+
+const sourcesGroup = getAndSet({
+  id: 'sources',
+  resource: 'sources',
+  method: 'PATCH',
+  getSummary: 'Get the internal-linking sources of a product.',
+  updateSummary: 'Change the primary or additional internal-linking sources from a JSON body.',
+  usage: SOURCES_USAGE,
+  guidance: 'Use `get` to inspect current linking sources and `update` to change the primary or additional sources.',
+  unknownNoun: 'linking-source',
+  aliases: ['set'],
+});
+
+const targetConfigGroup = getAndSet({
+  id: 'target-config',
+  resource: 'target-config',
+  method: 'PUT',
+  getSummary: 'Get the product-wide internal-linking target configuration.',
+  updateSummary: 'Replace the product-wide internal-linking target configuration from a JSON body.',
+  usage: TARGET_CONFIG_USAGE,
+  guidance: 'Use `get` to inspect product-wide linking target behavior and `update` to change it.',
+  unknownNoun: 'target-config',
+  aliases: [],
+});
+
+const detect = defineCommand({
+  id: 'products.linking.detect',
+  summary: 'Detect internal-linking targets for a product (long-running).',
+  kind: CommandKind.WRITE,
+  toolsets: TOOLSETS,
+  input: productInput(),
+  cli: PRODUCT_CLI,
+  longRunning: { pollTool: 'products.linking.targets.list' },
+  run: (input, ctx) => ctx.http({ method: 'POST', path: `${LINKING_PATH}/detect`, pathParams: productParams(input) }),
+});
+
+const targetsList = defineCommand({
+  id: 'products.linking.targets.list',
+  summary: 'List the saved internal-linking targets of a product.',
+  kind: CommandKind.READ,
+  toolsets: TOOLSETS,
+  input: productInput(),
+  cli: PRODUCT_CLI,
+  run: (input, ctx) => ctx.http({ method: 'GET', path: `${LINKING_PATH}/targets`, pathParams: productParams(input) }),
+});
+
+const targetsBody = ({ id, summary, suffix }) =>
+  defineCommand({
+    id: `products.linking.targets.${id}`,
+    summary,
+    kind: CommandKind.WRITE,
+    toolsets: TOOLSETS,
+    input: productInput(),
+    cli: PRODUCT_CLI,
+    body: BodyMode.JSON,
+    run: (input, ctx) =>
+      ctx.http({
+        method: 'POST',
+        path: `${LINKING_PATH}/targets/${suffix}`,
+        pathParams: productParams(input),
+        body: input.body,
+      }),
+  });
+
+const targetsAddManual = targetsBody({
+  id: 'add-manual',
+  summary: 'Add a manual internal-linking target from a JSON body.',
+  suffix: 'manual',
+});
+const targetsUpsert = targetsBody({
+  id: 'upsert',
+  summary: 'Upsert an internal-linking target from a JSON body.',
+  suffix: 'upsert',
+});
+
+const targetsClearCustomizations = defineCommand({
+  id: 'products.linking.targets.clear-customizations',
+  summary: 'Clear the manual customizations of one internal-linking target.',
+  kind: CommandKind.WRITE,
+  toolsets: TOOLSETS,
+  input: targetInput(),
+  cli: TARGET_CLI,
+  run: (input, ctx) => ctx.http({ method: 'PATCH', path: TARGET_PATH, pathParams: targetParams(input) }),
+});
+
+const targetsDelete = defineCommand({
+  id: 'products.linking.targets.delete',
+  summary: 'Delete one internal-linking target.',
+  kind: CommandKind.DESTRUCTIVE,
+  toolsets: TOOLSETS,
+  input: targetInput(),
+  cli: TARGET_CLI,
+  run: (input, ctx) => ctx.http({ method: 'DELETE', path: TARGET_PATH, pathParams: targetParams(input) }),
+});
+
+const targetsGroup = defineGroup({
+  id: 'products.linking.targets',
+  help: {
+    usage: TARGETS_USAGE,
+    guidance:
+      'Use `list` to inspect saved targets, `add-manual` or `upsert` to save URLs, and clear/delete for cleanup.',
+  },
+  unknown: (word) => ({
+    message: `Unknown products linking targets subcommand: ${word}.`,
+    guidance: 'Run `outrank-cli products linking targets --help` to see available linking-target commands.',
+  }),
+  children: [targetsList, targetsAddManual, targetsUpsert, targetsClearCustomizations, targetsDelete],
+});
+
+export const linkingGroup = defineGroup({
+  id: 'products.linking',
+  help: {
+    usage: LINKING_USAGE,
+    guidance:
+      'Use `sources` for source selection, `detect` for discovery, `targets` for saved URLs, and `target-config` ' +
+      'for product-wide rules.',
+  },
+  unknown: (word) => ({
+    message: `Unknown products linking subcommand: ${word}.`,
+    guidance: 'Run `outrank-cli products linking --help` to see available linking commands.',
+  }),
+  children: [sourcesGroup, detect, targetConfigGroup, targetsGroup],
+});

package/src/commands/products/shared.js

@@ -0,0 +1,8 @@
+import { uuid } from '../../core/schema.js';
+
+export const PRODUCT_CLI = { positionals: ['productId'] };
+
+export const productInput = () => ({ productId: uuid().required() });
+export const productParams = (input) => ({ productId: input.productId });
+
+export const withProduct = (extraPositionals) => ({ positionals: ['productId', ...extraPositionals] });

package/src/commands/registry.js

@@ -0,0 +1,272 @@
+import { MAX_TOOL_NAME_LENGTH, RESERVED_OPTION_NAMES } from '../core/constants.js';
+import { CliErrorCode, codedError, isEnvelope } from '../core/errors.js';
+import { isField, json, object } from '../core/schema.js';
+
+export const CommandKind = Object.freeze({
+  READ: 'read',
+  WRITE: 'write',
+  DESTRUCTIVE: 'destructive',
+  MONEY: 'money',
+  LOCAL: 'local',
+});
+
+export const Toolset = Object.freeze({
+  CORE: 'core',
+  INTEGRATIONS: 'integrations',
+  GSC: 'gsc',
+  LINKING: 'linking',
+  BACKLINKS: 'backlinks',
+  KEYWORDS: 'keywords',
+  ARTICLES: 'articles',
+  IMPROVEMENTS: 'improvements',
+  MARKETPLACE_SELLER: 'marketplace-seller',
+  MARKETPLACE_BUYER: 'marketplace-buyer',
+  BILLING: 'billing',
+});
+
+export const BodyMode = Object.freeze({
+  NONE: 'none',
+  EMPTY_OBJECT: 'empty-object',
+  JSON: 'json',
+  OPTIONAL_JSON: 'optional-json',
+  OPTIONAL_JSON_OR_EMPTY_OBJECT: 'optional-json-or-empty-object',
+});
+
+export const JSON_BODY_MODES = Object.freeze([
+  BodyMode.JSON,
+  BodyMode.OPTIONAL_JSON,
+  BodyMode.OPTIONAL_JSON_OR_EMPTY_OBJECT,
+]);
+
+export const NodeType = Object.freeze({
+  GROUP: 'group',
+  COMMAND: 'command',
+});
+
+export const BODY_INPUT_NAME = 'body';
+const MCP_FLAG_NAMES = Object.freeze(['sensitiveBody', 'untrustedOutput', 'redact']);
+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.';
+
+const registryError = (message) => new Error(`Command registry: ${message}`);
+
+export const toKebabCase = (name) => name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+export const toSnakeCase = (name) => name.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+export const cliWords = (id) => id.split('.');
+export const toolName = (id) => id.replaceAll('.', '_').replaceAll('-', '_');
+export const lastSegment = (id) => id.slice(id.lastIndexOf('.') + 1);
+export const optionField = (entry) => (typeof entry === 'string' ? entry : entry.field);
+
+const bodyInputFor = (body, bodyField, bodyMerge) => {
+  if (!JSON_BODY_MODES.includes(body)) return {};
+  const base = bodyField ?? (bodyMerge ? object() : json());
+  if (body === BodyMode.JSON) return { [BODY_INPUT_NAME]: base.required() };
+  if (body === BodyMode.OPTIONAL_JSON_OR_EMPTY_OBJECT) return { [BODY_INPUT_NAME]: base.default({}) };
+  return { [BODY_INPUT_NAME]: base };
+};
+
+const assertNoBodyInput = (id, input) => {
+  if (Object.hasOwn(input, BODY_INPUT_NAME)) {
+    throw registryError(`${id}: declare the request body with bodyField, not input.${BODY_INPUT_NAME}`);
+  }
+  return input;
+};
+
+const normalizeCommand = ({
+  id,
+  summary,
+  description,
+  input = {},
+  cli = {},
+  kind,
+  toolsets,
+  mcp = true,
+  body = BodyMode.NONE,
+  bodyField,
+  bodyMerge,
+  longRunning,
+  entryPoint = false,
+  offline = false,
+  allowUnknownProfile = false,
+  refine,
+  help,
+  run,
+}) => ({
+  type: NodeType.COMMAND,
+  id,
+  summary,
+  description: description ?? summary,
+  input: { ...assertNoBodyInput(id, input), ...bodyInputFor(body, bodyField, bodyMerge) },
+  cli,
+  kind,
+  toolsets,
+  mcp,
+  body,
+  bodyMerge,
+  longRunning,
+  entryPoint,
+  offline,
+  allowUnknownProfile,
+  refine,
+  help,
+  run,
+});
+
+export const defineCommand = (definition) => normalizeCommand(definition);
+
+export const defineGroup = ({ id, help, unknown, children, description, command }) => ({
+  type: NodeType.GROUP,
+  id,
+  help,
+  unknown,
+  description,
+  children,
+  ...(command ? { ...normalizeCommand({ ...command, id }), type: NodeType.GROUP, help, children } : {}),
+});
+
+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`);
+  for (const key of Object.keys(node.mcp)) {
+    if (!MCP_FLAG_NAMES.includes(key)) throw registryError(`${node.id}: unknown mcp flag ${key}`);
+  }
+  if (node.mcp.redact !== undefined && !Array.isArray(node.mcp.redact)) {
+    throw registryError(`${node.id}: mcp.redact must be an array of field names`);
+  }
+};
+
+const assertCliShape = (node) => {
+  const inputNames = Object.keys(node.input);
+  const positionals = node.cli.positionals ?? [];
+  for (const positional of positionals) {
+    if (!inputNames.includes(positional)) throw registryError(`${node.id}: positional ${positional} is not an input`);
+  }
+  const optionNames = new Set();
+  for (const [option, entry] of Object.entries(node.cli.options ?? {})) {
+    const field = optionField(entry);
+    if (!inputNames.includes(field)) {
+      throw registryError(`${node.id}: option --${option} maps to unknown input ${field}`);
+    }
+    if (RESERVED_OPTION_NAMES.includes(option)) throw registryError(`${node.id}: option --${option} is reserved`);
+    optionNames.add(option);
+  }
+  for (const name of inputNames) {
+    if (positionals.includes(name) || name === BODY_INPUT_NAME) continue;
+    const declared = Object.values(node.cli.options ?? {}).some((entry) => optionField(entry) === name);
+    const option = declared ? undefined : toKebabCase(name);
+    if (option !== undefined) {
+      if (RESERVED_OPTION_NAMES.includes(option)) throw registryError(`${node.id}: input ${name} shadows --${option}`);
+      if (optionNames.has(option)) throw registryError(`${node.id}: option --${option} is declared twice`);
+      optionNames.add(option);
+    }
+  }
+  for (const placeholder of Object.keys(node.cli.placeholders ?? {})) {
+    if (!inputNames.includes(placeholder)) {
+      throw registryError(`${node.id}: placeholder ${placeholder} is not an input`);
+    }
+  }
+  const snakeNames = inputNames.map(toSnakeCase);
+  if (new Set(snakeNames).size !== snakeNames.length) throw registryError(`${node.id}: snake_case input names collide`);
+};
+
+const assertCommandShape = (node) => {
+  if (!Object.values(CommandKind).includes(node.kind)) throw registryError(`${node.id}: unknown kind ${node.kind}`);
+  if (!Array.isArray(node.toolsets) || node.toolsets.length === 0) {
+    throw registryError(`${node.id}: toolsets must be a non-empty array`);
+  }
+  for (const toolset of node.toolsets) {
+    if (!Object.values(Toolset).includes(toolset)) throw registryError(`${node.id}: unknown toolset ${toolset}`);
+  }
+  if (typeof node.run !== 'function') throw registryError(`${node.id}: run must be a function`);
+  if (typeof node.summary !== 'string' || node.summary === '') throw registryError(`${node.id}: summary is required`);
+  const bodyIsMode = Object.values(BodyMode).includes(node.body);
+  const bodyIsFixed = Boolean(node.body) && typeof node.body === 'object';
+  if (!bodyIsMode && !bodyIsFixed) throw registryError(`${node.id}: body must be a BodyMode or a fixed object`);
+  if (node.bodyMerge !== undefined && (!JSON_BODY_MODES.includes(node.body) || typeof node.bodyMerge !== 'object')) {
+    throw registryError(`${node.id}: bodyMerge requires body: json and an object mapping`);
+  }
+  for (const field of Object.values(node.bodyMerge ?? {})) {
+    if (!(field in node.input)) throw registryError(`${node.id}: bodyMerge references unknown input ${field}`);
+  }
+  if (node.longRunning !== undefined && typeof node.longRunning?.pollTool !== 'string') {
+    throw registryError(`${node.id}: longRunning needs a pollTool id`);
+  }
+  if (node.refine !== undefined && typeof node.refine !== 'function') {
+    throw registryError(`${node.id}: refine must be a function`);
+  }
+  if (typeof node.offline !== 'boolean' || typeof node.allowUnknownProfile !== 'boolean') {
+    throw registryError(`${node.id}: offline and allowUnknownProfile must be booleans`);
+  }
+  for (const [name, field] of Object.entries(node.input)) {
+    if (!isField(field)) throw registryError(`${node.id}: input ${name} is not a field`);
+  }
+  assertMcpShape(node);
+  assertCliShape(node);
+  const name = toolName(node.id);
+  if (name.length > MAX_TOOL_NAME_LENGTH) throw registryError(`${node.id}: tool name ${name} is too long`);
+};
+
+const assertGroupShape = (node) => {
+  if (!node.help || typeof node.help.usage !== 'string') throw registryError(`${node.id}: group help is required`);
+  if (typeof node.unknown !== 'function') throw registryError(`${node.id}: group unknown() is required`);
+  const words = new Set();
+  for (const child of node.children ?? []) {
+    for (const word of [lastSegment(child.id), ...(child.cli?.aliases ?? [])]) {
+      if (words.has(word)) throw registryError(`${node.id}: duplicate child word ${word}`);
+      words.add(word);
+    }
+  }
+};
+
+const walk = (node, parentId, seen, commands) => {
+  if (!ID_PATTERN.test(node.id)) throw registryError(`invalid id ${node.id}`);
+  if (parentId !== null && !node.id.startsWith(`${parentId}.`)) {
+    throw registryError(`${node.id} must be nested under ${parentId}`);
+  }
+  if (seen.has(node.id)) throw registryError(`duplicate id ${node.id}`);
+  seen.add(node.id);
+  if (node.type === NodeType.COMMAND) {
+    assertCommandShape(node);
+    commands.push(node);
+    return;
+  }
+  assertGroupShape(node);
+  if (node.run !== undefined) {
+    assertCommandShape(node);
+    commands.push(node);
+  }
+  for (const child of node.children ?? []) walk(child, node.id, seen, commands);
+};
+
+export const createRegistry = (groups) => {
+  const seen = new Set();
+  const commands = [];
+  for (const group of groups) {
+    if (group.type !== NodeType.GROUP) throw registryError(`${group.id} is not a group`);
+    walk(group, null, seen, commands);
+  }
+  const byId = new Map(commands.map((command) => [command.id, command]));
+  const byToolName = new Map();
+  for (const command of commands) {
+    const name = toolName(command.id);
+    if (byToolName.has(name)) {
+      throw registryError(`tool name ${name} is used by ${byToolName.get(name).id} and ${command.id}`);
+    }
+    byToolName.set(name, command);
+    if (command.longRunning && !byId.has(command.longRunning.pollTool)) {
+      throw registryError(`${command.id}: pollTool ${command.longRunning.pollTool} is not a command`);
+    }
+  }
+  return Object.freeze({ groups, commands, byId, byToolName });
+};
+
+export const findChild = (group, word) =>
+  (group.children ?? []).find((child) => lastSegment(child.id) === word || child.cli?.aliases?.includes(word));
+
+export const assertEnvelope = (node, result) => {
+  if (!isEnvelope(result)) {
+    const message = `Command ${node.id} returned no result envelope.`;
+    throw codedError(CliErrorCode.UNEXPECTED_ERROR, message, NO_RESULT_GUIDANCE);
+  }
+  return result;
+};

package/src/commands/subscription.js

@@ -1,6 +1,4 @@
-import { hasFlag, parseArgs } from '../core/args.js';
-import { requestAgentApi } from '../core/api.js';
-import { cliSuccess } from '../core/errors.js';
+import { CommandKind, Toolset, defineCommand, defineGroup } from './registry.js';
 
 export const SUBSCRIPTION_HELP = `Usage:
   outrank-cli subscription status
@@ -9,31 +7,23 @@ Commands:
   status    Return the current subscription, plan, trial, quota, and add-on status.
 `;
 
-export const handleSubscriptionCommand = async (argv) => {
-  const subcommand = argv[0];
-  const parsed = parseArgs(argv.slice(1));
-  const wantsHelp =
-    !subcommand || subcommand === '--help' || subcommand === '-h' || subcommand === 'help' || hasFlag(parsed, 'help');
-
-  if (wantsHelp) {
-    return cliSuccess(
-      {
-        usage: SUBSCRIPTION_HELP.trim(),
-      },
-      'Use `status` to inspect the current plan, quota, trial, and add-on state.',
-    );
-  }
-
-  if (subcommand === 'status') {
-    const response = await requestAgentApi(parsed, {
-      method: 'GET',
-      path: '/subscription/status',
-    });
-    return response.payload;
-  }
-
-  throw Object.assign(new Error(`Unknown subscription subcommand: ${subcommand}.`), {
-    cliCode: 'CLI_INVALID_USAGE',
+export const subscriptionGroup = defineGroup({
+  id: 'subscription',
+  help: {
+    usage: SUBSCRIPTION_HELP,
+    guidance: 'Use `status` to inspect the current plan, quota, trial, and add-on state.',
+  },
+  unknown: (word) => ({
+    message: `Unknown subscription subcommand: ${word}.`,
     guidance: 'Run `outrank-cli subscription --help` to see available subscription commands.',
-  });
-};
+  }),
+  children: [
+    defineCommand({
+      id: 'subscription.status',
+      summary: 'Return the current subscription, plan, trial, quota, and add-on status.',
+      kind: CommandKind.READ,
+      toolsets: [Toolset.CORE],
+      run: (_input, ctx) => ctx.http({ method: 'GET', path: '/subscription/status' }),
+    }),
+  ],
+});

package/src/commands/usage.js

@@ -1,6 +1,4 @@
-import { hasFlag, parseArgs } from '../core/args.js';
-import { requestAgentApi } from '../core/api.js';
-import { cliSuccess } from '../core/errors.js';
+import { CommandKind, Toolset, defineCommand, defineGroup } from './registry.js';
 
 export const USAGE_HELP = `Usage:
   outrank-cli usage stats
@@ -9,31 +7,20 @@ Commands:
   stats    Return current usage and quota metrics for articles, backlinks, free tools, and product slots.
 `;
 
-export const handleUsageCommand = async (argv) => {
-  const subcommand = argv[0];
-  const parsed = parseArgs(argv.slice(1));
-  const wantsHelp =
-    !subcommand || subcommand === '--help' || subcommand === '-h' || subcommand === 'help' || hasFlag(parsed, 'help');
-
-  if (wantsHelp) {
-    return cliSuccess(
-      {
-        usage: USAGE_HELP.trim(),
-      },
-      'Use `stats` to inspect current quota consumption and activity.',
-    );
-  }
-
-  if (subcommand === 'stats') {
-    const response = await requestAgentApi(parsed, {
-      method: 'GET',
-      path: '/usage/stats',
-    });
-    return response.payload;
-  }
-
-  throw Object.assign(new Error(`Unknown usage subcommand: ${subcommand}.`), {
-    cliCode: 'CLI_INVALID_USAGE',
+export const usageGroup = defineGroup({
+  id: 'usage',
+  help: { usage: USAGE_HELP, guidance: 'Use `stats` to inspect current quota consumption and activity.' },
+  unknown: (word) => ({
+    message: `Unknown usage subcommand: ${word}.`,
     guidance: 'Run `outrank-cli usage --help` to see available usage commands.',
-  });
-};
+  }),
+  children: [
+    defineCommand({
+      id: 'usage.stats',
+      summary: 'Return current usage and quota metrics for articles, backlinks, free tools, and product slots.',
+      kind: CommandKind.READ,
+      toolsets: [Toolset.CORE],
+      run: (_input, ctx) => ctx.http({ method: 'GET', path: '/usage/stats' }),
+    }),
+  ],
+});