outrank-cli 0.5.0 → 0.6.0

package/src/core/config.js

@@ -1,80 +1,261 @@
+import { randomBytes } from 'node:crypto';
 import os from 'node:os';
 import path from 'node:path';
 import fs from 'node:fs/promises';
 
-import { ensureDirectory, fileExists } from './io.js';
+import {
+  API_KEY_SUFFIX_LENGTH,
+  CONFIG_DIR_MODE,
+  CONFIG_FILE_MODE,
+  CONFIG_TEMP_SUFFIX_BYTES,
+  DEFAULT_PROFILE_NAME,
+  MAX_CONFIG_SYMLINK_HOPS,
+  MAX_PROFILE_NAME_LENGTH,
+  MIN_API_KEY_LENGTH_FOR_SUFFIX,
+  PROFILE_NAME_PATTERN,
+} from './constants.js';
+import { CliErrorCode, codedError } from './errors.js';
 
-const DEFAULT_BASE_URL = 'https://www.outrank.so';
+const CONFIG_DIR_ENV = 'OUTRANK_CONFIG_DIR';
+const CONFIG_DIR_NAME = '.outrank';
+const CONFIG_FILE_NAME = 'config.json';
+const TEMP_FILE_EXTENSION = '.tmp';
+const BYTE_ORDER_MARK = '';
+const PRINTABLE_ASCII_PATTERN = /^[\x20-\x7e]$/;
+const TRUNCATION_MARK = '...';
+export const API_KEY_FIELD = 'apiKey';
+export const BASE_URL_FIELD = 'baseUrl';
+const DEFAULT_PROFILE_FIELD = 'defaultProfile';
+const PROFILES_FIELD = 'profiles';
+const PROFILE_FIELDS = Object.freeze([API_KEY_FIELD, BASE_URL_FIELD]);
+const MANAGED_TOP_LEVEL_KEYS = new Set([API_KEY_FIELD, BASE_URL_FIELD, DEFAULT_PROFILE_FIELD, PROFILES_FIELD]);
+const MISSING_FILE_CODE = 'ENOENT';
+const SYMLINK_LOOP_CODE = 'ELOOP';
+const UNKNOWN_FS_ERROR_REASON = 'unknown filesystem error';
+const INVALID_JSON_REASON = 'it is not valid JSON';
+const NOT_AN_OBJECT_REASON = 'it is not a JSON object';
+const CONFIG_UNREADABLE_GUIDANCE =
+  'Fix or delete the file at details.config_path, or point OUTRANK_CONFIG_DIR at another directory, then retry. ' +
+  '`auth login` and `auth logout` never overwrite a config file they cannot fully parse.';
+const CONFIG_UNWRITABLE_GUIDANCE =
+  'Nothing was saved. Check that details.config_path is writable and not locked by another program, or point ' +
+  'OUTRANK_CONFIG_DIR at a writable directory, then run the command again.';
 
-const getConfigDir = () => process.env.OUTRANK_CONFIG_DIR || path.join(os.homedir(), '.outrank');
-export const getConfigPath = () => path.join(getConfigDir(), 'config.json');
+const getConfigDir = () => {
+  const override = process.env[CONFIG_DIR_ENV];
+  return override ? path.resolve(override) : path.join(os.homedir(), CONFIG_DIR_NAME);
+};
+export const getConfigPath = () => path.join(getConfigDir(), CONFIG_FILE_NAME);
+
+export const isSet = (value) => typeof value === 'string' && value !== '';
+const isPlainObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+export const isValidProfileName = (name) =>
+  typeof name === 'string' && name.length <= MAX_PROFILE_NAME_LENGTH && PROFILE_NAME_PATTERN.test(name);
+
+export const redactApiKey = (apiKey) =>
+  typeof apiKey === 'string' && apiKey.length >= MIN_API_KEY_LENGTH_FOR_SUFFIX
+    ? apiKey.slice(-API_KEY_SUFFIX_LENGTH)
+    : null;
+
+const ownEntry = (source, name) => (isPlainObject(source) && Object.hasOwn(source, name) ? source[name] : undefined);
+
+const pickProfileFields = (source) =>
+  Object.fromEntries(PROFILE_FIELDS.filter((field) => isSet(source?.[field])).map((field) => [field, source[field]]));
+
+const preservedProfileFields = (source) =>
+  Object.fromEntries(Object.entries(source ?? {}).filter(([key]) => !PROFILE_FIELDS.includes(key)));
+
+const omitField = (source, field) => Object.fromEntries(Object.entries(source).filter(([key]) => key !== field));
+
+const configUnreadableError = (reason) =>
+  codedError(
+    CliErrorCode.CONFIG_UNREADABLE,
+    `The stored config file could not be read: ${reason}.`,
+    CONFIG_UNREADABLE_GUIDANCE,
+    { config_path: getConfigPath() },
+  );
+
+const configUnwritableError = (error) =>
+  codedError(
+    CliErrorCode.CONFIG_UNWRITABLE,
+    `The config file could not be written: ${error.code ?? UNKNOWN_FS_ERROR_REASON}.`,
+    CONFIG_UNWRITABLE_GUIDANCE,
+    { config_path: getConfigPath(), fs_code: error.code ?? null },
+  );
+
+const isPrintableAscii = (character) => PRINTABLE_ASCII_PATTERN.test(character);
+
+export const describeUntrustedValue = (value) => {
+  if (typeof value !== 'string') return `a non-string value (${value === null ? 'null' : typeof value})`;
+  const printable = [...value].filter(isPrintableAscii).join('');
+  const excerpt = printable.slice(0, MAX_PROFILE_NAME_LENGTH);
+  return JSON.stringify(excerpt.length < printable.length ? `${excerpt}${TRUNCATION_MARK}` : excerpt);
+};
+
+const fieldTypeProblem = (owner, entry) => {
+  for (const field of PROFILE_FIELDS) {
+    if (entry[field] !== undefined && typeof entry[field] !== 'string') return `${owner} has a non-string ${field}`;
+  }
+  return null;
+};
+
+const profilesShapeProblem = (profiles) => {
+  if (profiles === undefined) return null;
+  if (!isPlainObject(profiles)) return `${PROFILES_FIELD} is not a JSON object`;
+  for (const [name, entry] of Object.entries(profiles)) {
+    if (!isValidProfileName(name)) return `profile name ${describeUntrustedValue(name)} is invalid`;
+    if (!isPlainObject(entry)) return `profile ${describeUntrustedValue(name)} is not a JSON object`;
+    const problem = fieldTypeProblem(`profile ${describeUntrustedValue(name)}`, entry);
+    if (problem) return problem;
+  }
+  return null;
+};
+
+const configShapeProblem = (raw) => {
+  if (!isPlainObject(raw)) return null;
+  const topLevelProblem = fieldTypeProblem('the config file', raw);
+  if (topLevelProblem) return topLevelProblem;
+  const defaultProfile = ownEntry(raw, DEFAULT_PROFILE_FIELD);
+  if (defaultProfile !== undefined && !isValidProfileName(defaultProfile)) {
+    return `${DEFAULT_PROFILE_FIELD} ${describeUntrustedValue(defaultProfile)} is not a valid profile name`;
+  }
+  return profilesShapeProblem(ownEntry(raw, PROFILES_FIELD));
+};
+
+export const readProfiles = (raw) => {
+  const problem = configShapeProblem(raw);
+  if (problem) throw configUnreadableError(problem);
+  const mirror = pickProfileFields(raw);
+  const defaultProfile = ownEntry(raw, DEFAULT_PROFILE_FIELD) ?? DEFAULT_PROFILE_NAME;
+  const rawProfiles = ownEntry(raw, PROFILES_FIELD);
+  if (rawProfiles === undefined) {
+    const profiles = Object.keys(mirror).length > 0 ? { [defaultProfile]: mirror } : {};
+    return { defaultProfile, profiles };
+  }
+  const profiles = Object.fromEntries(
+    Object.entries(rawProfiles).map(([name, entry]) => [name, pickProfileFields(entry)]),
+  );
+  if (Object.keys(mirror).length > 0) profiles[defaultProfile] = mirror;
+  return { defaultProfile, profiles };
+};
+
+export const serializeProfiles = (raw, { defaultProfile, profiles }) => {
+  const rawProfiles = ownEntry(raw, PROFILES_FIELD) ?? {};
+  const preserved = Object.fromEntries(
+    Object.entries(isPlainObject(raw) ? raw : {}).filter(([key]) => !MANAGED_TOP_LEVEL_KEYS.has(key)),
+  );
+  const merged = Object.fromEntries(
+    Object.entries(profiles).map(([name, entry]) => [
+      name,
+      { ...preservedProfileFields(ownEntry(rawProfiles, name)), ...entry },
+    ]),
+  );
+  return { ...pickProfileFields(profiles[defaultProfile]), defaultProfile, profiles: merged, ...preserved };
+};
 
 export const loadConfig = async () => {
-  const configPath = getConfigPath();
-  if (!(await fileExists(configPath))) {
-    return {};
+  let text;
+  try {
+    text = await fs.readFile(getConfigPath(), 'utf8');
+  } catch (error) {
+    if (error.code === MISSING_FILE_CODE) return {};
+    throw configUnreadableError(error.code ?? UNKNOWN_FS_ERROR_REASON);
+  }
+  let config;
+  try {
+    config = JSON.parse(text.startsWith(BYTE_ORDER_MARK) ? text.slice(BYTE_ORDER_MARK.length) : text);
+  } catch {
+    throw configUnreadableError(INVALID_JSON_REASON);
+  }
+  if (!isPlainObject(config)) throw configUnreadableError(NOT_AN_OBJECT_REASON);
+  const problem = configShapeProblem(config);
+  if (problem) throw configUnreadableError(problem);
+  return config;
+};
+
+export const loadProfiles = async () => readProfiles(await loadConfig());
+
+const isSymbolicLink = async (filePath) => {
+  try {
+    return (await fs.lstat(filePath)).isSymbolicLink();
+  } catch (error) {
+    if (error.code === MISSING_FILE_CODE) return false;
+    throw error;
+  }
+};
+
+const resolveDanglingLink = async (filePath) => {
+  let current = filePath;
+  for (let hop = 0; hop < MAX_CONFIG_SYMLINK_HOPS; hop += 1) {
+    if (!(await isSymbolicLink(current))) return current;
+    const directory = await fs.realpath(path.dirname(current));
+    current = path.resolve(directory, await fs.readlink(current));
+  }
+  throw Object.assign(new Error(`Too many symbolic links at ${filePath}`), { code: SYMLINK_LOOP_CODE });
+};
+
+const resolveWriteTarget = async (filePath) => {
+  try {
+    return await fs.realpath(filePath);
+  } catch (error) {
+    if (error.code === MISSING_FILE_CODE) return resolveDanglingLink(filePath);
+    throw error;
   }
+};
 
-  const raw = await fs.readFile(configPath, 'utf8');
+const removeQuietly = async (filePath) => {
   try {
-    const config = JSON.parse(raw);
-    return config && typeof config === 'object' ? config : {};
+    await fs.rm(filePath, { force: true });
   } catch {
-    return {};
+    return;
   }
 };
 
-export const saveConfig = async (config) => {
-  const configPath = getConfigPath();
-  await ensureDirectory(path.dirname(configPath));
-  await fs.writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+const writeFileAtomically = async (filePath, text) => {
+  await fs.mkdir(path.dirname(filePath), { recursive: true, mode: CONFIG_DIR_MODE });
+  const target = await resolveWriteTarget(filePath);
+  const suffix = randomBytes(CONFIG_TEMP_SUFFIX_BYTES).toString('hex');
+  const tempPath = `${target}.${process.pid}.${suffix}${TEMP_FILE_EXTENSION}`;
+  try {
+    await fs.writeFile(tempPath, text, { encoding: 'utf8', mode: CONFIG_FILE_MODE, flag: 'wx' });
+    await fs.chmod(tempPath, CONFIG_FILE_MODE);
+    await fs.rename(tempPath, target);
+  } catch (error) {
+    await removeQuietly(tempPath);
+    throw error;
+  }
 };
 
-export const clearStoredAuth = async () => {
-  const configPath = getConfigPath();
-  const current = await loadConfig();
-  if (!(await fileExists(configPath))) {
-    return current;
+export const saveProfiles = async (raw, state) => {
+  const serialized = serializeProfiles(raw, state);
+  try {
+    await writeFileAtomically(getConfigPath(), `${JSON.stringify(serialized, null, 2)}\n`);
+  } catch (error) {
+    throw configUnwritableError(error);
   }
-  const next = { ...current };
-  delete next.apiKey;
-  await saveConfig(next);
-  return next;
-};
-
-const normalizeBaseUrl = (value) => {
-  const url = new URL(value || DEFAULT_BASE_URL);
-  return url.origin.replace(/\/$/, '');
-};
-
-export const resolveRuntimeConfig = async (parsed) => {
-  const config = await loadConfig();
-  const apiKey =
-    process.env.OUTRANK_API_KEY ||
-    (parsed ? parsed.options.get('api-key')?.slice(-1)[0] : undefined) ||
-    config.apiKey;
-  const baseUrl =
-    process.env.OUTRANK_BASE_URL ||
-    (parsed ? parsed.options.get('base-url')?.slice(-1)[0] : undefined) ||
-    config.baseUrl ||
-    DEFAULT_BASE_URL;
-
-  return {
-    apiKey,
-    baseUrl: normalizeBaseUrl(baseUrl),
-    config,
-  };
-};
-
-export const storeAuthConfig = async ({ apiKey, baseUrl }) => {
-  const current = await loadConfig();
-  const next = {
-    ...current,
-    ...(apiKey ? { apiKey } : {}),
-    ...(baseUrl ? { baseUrl: normalizeBaseUrl(baseUrl) } : {}),
-  };
-  await saveConfig(next);
-  return next;
-};
-
-export const getDefaultBaseUrl = () => DEFAULT_BASE_URL;
+  return serialized;
+};
+
+const hasStoredApiKey = (profiles) => Object.values(profiles).some((profile) => isSet(profile[API_KEY_FIELD]));
+
+export const storeProfileAuth = async ({ profile, apiKey, baseUrl, makeDefault = false }) => {
+  const raw = await loadConfig();
+  const state = readProfiles(raw);
+  const stored = { ...(ownEntry(state.profiles, profile) ?? {}), [API_KEY_FIELD]: apiKey };
+  if (baseUrl) stored[BASE_URL_FIELD] = baseUrl;
+  const profiles = { ...state.profiles, [profile]: stored };
+  const defaultProfile = makeDefault || !hasStoredApiKey(state.profiles) ? profile : state.defaultProfile;
+  await saveProfiles(raw, { defaultProfile, profiles });
+  return { profile, isDefault: defaultProfile === profile, stored, defaultProfile, profiles };
+};
+
+export const clearProfileAuth = async ({ profile }) => {
+  const raw = await loadConfig();
+  const state = readProfiles(raw);
+  const entry = ownEntry(state.profiles, profile);
+  if (!entry || !isSet(entry[API_KEY_FIELD])) return { ...state, removed: false };
+  const profiles = { ...state.profiles, [profile]: omitField(entry, API_KEY_FIELD) };
+  await saveProfiles(raw, { defaultProfile: state.defaultProfile, profiles });
+  return { defaultProfile: state.defaultProfile, profiles, removed: true };
+};

package/src/core/constants.js

@@ -0,0 +1,101 @@
+const BYTES_PER_MB = 1024 * 1024;
+
+export const API_BASE_PATH = '/api/agent/v1';
+export const DEFAULT_BASE_URL = 'https://www.outrank.so';
+export const ALLOWED_BASE_URL_HOSTS = Object.freeze(['www.outrank.so', 'outrank.so']);
+export const LOOPBACK_HOSTNAMES = Object.freeze(['localhost', '127.0.0.1', '[::1]']);
+export const ALLOW_CUSTOM_BASE_URL_ENV = 'OUTRANK_ALLOW_CUSTOM_BASE_URL';
+export const API_KEY_ENV = 'OUTRANK_API_KEY';
+export const BASE_URL_ENV = 'OUTRANK_BASE_URL';
+export const PROFILE_ENV = 'OUTRANK_PROFILE';
+export const ProfileSource = Object.freeze({
+  FLAG: 'flag',
+  ENV: 'env',
+  DEFAULT: 'default',
+});
+export const Surface = Object.freeze({ CLI: 'cli', MCP: 'mcp' });
+export const DEFAULT_PROFILE_NAME = 'default';
+export const PROFILE_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+export const MAX_PROFILE_NAME_LENGTH = 64;
+export const API_KEY_SUFFIX_LENGTH = 4;
+export const MIN_API_KEY_LENGTH_FOR_SUFFIX = 8;
+export const HEADER_SAFE_API_KEY_PATTERN = /^[\x21-\x7e]+$/;
+
+export const HTTP_REQUEST_TIMEOUT_MS = 60_000;
+export const HTTP_LONG_RUNNING_TIMEOUT_MS = 330_000;
+export const MCP_STARTUP_RESOLVE_TIMEOUT_MS = 3_000;
+
+export const MAX_IMAGE_UPLOAD_MEGABYTES = 5;
+export const MAX_IMAGE_UPLOAD_BYTES = MAX_IMAGE_UPLOAD_MEGABYTES * BYTES_PER_MB;
+export const MAX_UPSTREAM_ERROR_BODY_CHARS = 500;
+export const MAX_RATE_LIMIT_HEADER_LENGTH = 64;
+export const MAX_TOOL_NAME_LENGTH = 46;
+
+export const LIST_MIN_LIMIT = 1;
+export const LIST_MAX_LIMIT = 100;
+export const MIN_OFFSET = 0;
+export const MIN_SEARCH_VOLUME = 0;
+export const MIN_DIFFICULTY = 0;
+export const MAX_DIFFICULTY = 100;
+export const KEYWORDS_SUGGEST_MAX_LIMIT = 20;
+export const IMPROVEMENTS_CANDIDATES_MAX_LIMIT = 50;
+export const GSC_MIN_MONTHS = 1;
+export const GSC_MAX_MONTHS = 16;
+export const GSC_SEARCH_ANALYTICS_MAX_LIMIT = 1000;
+export const KEYWORDS_GENERATE_MIN_COUNT = 5;
+export const KEYWORDS_GENERATE_MAX_COUNT = 30;
+
+export const BILLING_MIN_ADDITIONAL_PRODUCTS = 1;
+export const BILLING_MAX_ADDITIONAL_PRODUCTS = 30;
+export const BILLING_MIN_CONFIRM_CHARGE_CENTS = 0;
+
+export const HttpStatus = Object.freeze({
+  NO_CONTENT: 204,
+  RESET_CONTENT: 205,
+  NOT_FOUND: 404,
+  CONFLICT: 409,
+  TOO_MANY_REQUESTS: 429,
+  BAD_GATEWAY: 502,
+  GATEWAY_TIMEOUT: 504,
+});
+export const HTTP_STATUS_CONFLICT = HttpStatus.CONFLICT;
+export const NO_BODY_STATUSES = Object.freeze([HttpStatus.NO_CONTENT, HttpStatus.RESET_CONTENT]);
+export const LONG_RUNNING_GATEWAY_STATUSES = Object.freeze([HttpStatus.BAD_GATEWAY, HttpStatus.GATEWAY_TIMEOUT]);
+
+export const JSON_CONTENT_TYPE = 'application/json';
+export const CONFIG_FILE_MODE = 0o600;
+export const CONFIG_DIR_MODE = 0o700;
+export const CONFIG_TEMP_SUFFIX_BYTES = 6;
+export const MAX_CONFIG_SYMLINK_HOPS = 8;
+
+export const RESERVED_OPTION_NAMES = Object.freeze([
+  'api-key',
+  'base-url',
+  'allow-custom-base-url',
+  'profile',
+  'json',
+  'json-file',
+  'json-stdin',
+  'help',
+]);
+
+export const RATE_LIMIT_HEADERS = Object.freeze({
+  retryAfter: 'retry-after',
+  limitMinute: 'x-ratelimit-limit-minute',
+  remainingMinute: 'x-ratelimit-remaining-minute',
+  limitDay: 'x-ratelimit-limit-day',
+  remainingDay: 'x-ratelimit-remaining-day',
+});
+
+export const SENSITIVE_BODY_FIELDS = Object.freeze([
+  'api_key',
+  'apiKey',
+  'api_token',
+  'access_token',
+  'refresh_token',
+  'server_api_key',
+  'secret',
+  'password',
+  'token',
+  'authorization',
+]);