outrank-cli 0.5.0 → 0.6.0

package/src/core/context.js

@@ -0,0 +1,311 @@
+import {
+  ALLOWED_BASE_URL_HOSTS,
+  ALLOW_CUSTOM_BASE_URL_ENV,
+  API_KEY_ENV,
+  BASE_URL_ENV,
+  DEFAULT_BASE_URL,
+  LOOPBACK_HOSTNAMES,
+  PROFILE_ENV,
+  ProfileSource,
+  Surface,
+} from './constants.js';
+import { CliErrorCode, codedError } from './errors.js';
+import {
+  describeUntrustedValue,
+  getConfigPath,
+  isSet,
+  isValidProfileName,
+  loadConfig,
+  readProfiles,
+} from './config.js';
+import { requestAgentApi } from './http.js';
+import { profileSelectedByEnvHint } from './profileSelection.js';
+
+export { ProfileSource, Surface };
+
+export const ContextSource = Object.freeze({
+  FLAG: 'flag',
+  ENV: 'env',
+  PROFILE: 'profile',
+  DEFAULT: 'default',
+  MISSING: 'missing',
+});
+
+const TRUTHY_ENV_VALUES = new Set(['1', 'true', 'yes']);
+const HTTPS_PROTOCOL = 'https:';
+const HTTP_PROTOCOL = 'http:';
+const CLI_BINARY = 'outrank-cli';
+const PROFILE_FLAG = '--profile';
+
+const pickFirst = (candidates) => candidates.find(([, value]) => isSet(value)) ?? [ContextSource.MISSING, undefined];
+
+const baseUrlGuidance =
+  'Pass a full https origin such as https://www.outrank.so via --base-url or OUTRANK_BASE_URL, or remove the ' +
+  'override to use the default.';
+
+const allowlistGuidance = (host) =>
+  `Only ${ALLOWED_BASE_URL_HOSTS.join(', ')} are accepted by default. If ${host} is a deployment you control, set ` +
+  `${ALLOW_CUSTOM_BASE_URL_ENV}=1 or pass --allow-custom-base-url. Never point a real API key at an unknown host.`;
+
+const cleartextGuidance =
+  'The API key travels in the Authorization header, so only https is accepted. Plain http is allowed only for ' +
+  `loopback hosts (${LOOPBACK_HOSTNAMES.join(', ')}) together with ${ALLOW_CUSTOM_BASE_URL_ENV}=1.`;
+
+const storedProfileOnlyGuidance = (host) =>
+  `This server sends the API key to ${ALLOWED_BASE_URL_HOSTS.join(' or ')} only, unless both the key and the base ` +
+  `URL come from the same stored profile. If ${host} is a deployment you control, run ` +
+  '`outrank-cli auth login <api-key> --profile <name> --base-url <url> --allow-custom-base-url` in a terminal, ' +
+  'then start the server with `--profile <name>`. Environment variables cannot unlock a custom host here.';
+
+const profileNameGuidance =
+  'Profile names start with a letter or digit and may contain letters, digits, dots, dashes and underscores.';
+
+const describeProfileSource = (source) => (source === ProfileSource.ENV ? PROFILE_ENV : PROFILE_FLAG);
+
+const HIDDEN_PROFILES_NOTE = 'Run `outrank-cli auth profiles` in a terminal to see the stored profiles.';
+
+const describeStoredProfiles = (profiles, revealLocalDetails) => {
+  if (!revealLocalDetails) return HIDDEN_PROFILES_NOTE;
+  const names = Object.keys(profiles).sort();
+  return names.length === 0
+    ? 'No profiles are stored yet.'
+    : `Stored profiles: ${names.join(', ')}. Run \`outrank-cli auth profiles\` to inspect them.`;
+};
+
+const unknownProfileGuidance = (profiles, source, revealLocalDetails) => {
+  const stored = describeStoredProfiles(profiles, revealLocalDetails);
+  return (
+    `${stored} Run \`outrank-cli auth login <api-key> --profile <name>\` to create a new one.` +
+    profileSelectedByEnvHint(source)
+  );
+};
+
+const configFileReference = (revealLocalDetails) =>
+  revealLocalDetails
+    ? 'the config file at details.config_path'
+    : 'the outrank-cli config file (run `outrank-cli auth status` in a terminal to see its path)';
+
+const storedBaseUrlGuidance = (profile, revealLocalDetails) =>
+  `Edit the baseUrl of profile ${profile} in ${configFileReference(revealLocalDetails)}, run ` +
+  `\`outrank-cli auth login <api-key> --profile ${profile} --base-url <url>\` to replace it, or pass --base-url ` +
+  'for this call. `auth status`, `auth profiles` and `auth logout` keep working with the broken value.';
+
+const emptyFlagError = (flag) =>
+  codedError(
+    CliErrorCode.INVALID_USAGE,
+    `${flag} was given without a value.`,
+    `Pass a value after ${flag}, or drop the option to fall back to the environment or the stored config.`,
+  );
+
+const invalidBaseUrlError = (shown) =>
+  codedError(CliErrorCode.INVALID_USAGE, `Invalid base URL: ${shown}`, baseUrlGuidance);
+
+export const normalizeBaseUrl = (value) => {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw invalidBaseUrlError(describeUntrustedValue(value));
+  }
+  if (url.protocol !== HTTPS_PROTOCOL && url.protocol !== HTTP_PROTOCOL) {
+    throw invalidBaseUrlError(JSON.stringify(`${url.protocol}//${url.host}`));
+  }
+  return url.origin;
+};
+
+const assertAllowedBaseUrl = (baseUrl, allowCustomBaseUrl, guidanceFor = allowlistGuidance) => {
+  const url = new URL(baseUrl);
+  const loopback = LOOPBACK_HOSTNAMES.includes(url.hostname) || LOOPBACK_HOSTNAMES.includes(`[${url.hostname}]`);
+  if (url.protocol === HTTP_PROTOCOL && !(loopback && allowCustomBaseUrl)) {
+    throw codedError(CliErrorCode.INVALID_USAGE, `Base URL ${baseUrl} is not https.`, cleartextGuidance);
+  }
+  if (allowCustomBaseUrl || ALLOWED_BASE_URL_HOSTS.includes(url.host)) return;
+  throw codedError(
+    CliErrorCode.INVALID_USAGE,
+    `Base URL host ${url.host} is not allowed.`,
+    guidanceFor(url.host),
+  );
+};
+
+const assertFlagsHaveValues = (flags) => {
+  if (flags.apiKey === '') throw emptyFlagError('--api-key');
+  if (flags.baseUrl === '') throw emptyFlagError('--base-url');
+  if (flags.profile === '') throw emptyFlagError('--profile');
+};
+
+const selectProfile = ({ flags, env, state, allowUnknownProfile, revealLocalDetails }) => {
+  const [source, name] = pickFirst([
+    [ProfileSource.FLAG, flags.profile],
+    [ProfileSource.ENV, env[PROFILE_ENV]],
+    [ProfileSource.DEFAULT, state.defaultProfile],
+  ]);
+  if (!isValidProfileName(name)) {
+    throw codedError(
+      CliErrorCode.INVALID_USAGE,
+      `Invalid profile name ${describeUntrustedValue(name)} (from ${describeProfileSource(source)}).`,
+      profileNameGuidance,
+    );
+  }
+  const explicit = source !== ProfileSource.DEFAULT;
+  const known = Object.hasOwn(state.profiles, name);
+  if (explicit && !known && !allowUnknownProfile) {
+    throw codedError(
+      CliErrorCode.INVALID_USAGE,
+      `Unknown profile: ${name} (from ${describeProfileSource(source)}).`,
+      unknownProfileGuidance(state.profiles, source, revealLocalDetails),
+    );
+  }
+  return { name, source, explicit, known, values: known ? state.profiles[name] : {} };
+};
+
+const normalizeResolvedBaseUrl = ({ value, source, profileName, tolerateStored, revealLocalDetails }) => {
+  try {
+    return normalizeBaseUrl(value);
+  } catch (error) {
+    if (source !== ContextSource.PROFILE) throw error;
+    if (tolerateStored) return null;
+    throw codedError(
+      CliErrorCode.INVALID_USAGE,
+      `Invalid base URL stored in profile ${profileName}.`,
+      storedBaseUrlGuidance(profileName, revealLocalDetails),
+      { config_path: getConfigPath() },
+    );
+  }
+};
+
+export const resolveContext = ({
+  flags = {},
+  env = {},
+  config = {},
+  enforceAllowlist = true,
+  allowUnknownProfile = false,
+  customBaseUrlFromStoredProfileOnly = false,
+  revealLocalDetails = true,
+} = {}) => {
+  assertFlagsHaveValues(flags);
+  const profile = selectProfile({
+    flags,
+    env,
+    state: readProfiles(config),
+    allowUnknownProfile,
+    revealLocalDetails,
+  });
+  const envApiKey = profile.explicit ? undefined : env[API_KEY_ENV];
+  const envBaseUrl = profile.explicit ? undefined : env[BASE_URL_ENV];
+  const [apiKeySource, apiKey] = pickFirst([
+    [ContextSource.FLAG, flags.apiKey],
+    [ContextSource.ENV, envApiKey],
+    [ContextSource.PROFILE, profile.values.apiKey],
+  ]);
+  const [baseUrlSource, rawBaseUrl] = pickFirst([
+    [ContextSource.FLAG, flags.baseUrl],
+    [ContextSource.ENV, envBaseUrl],
+    [ContextSource.PROFILE, profile.values.baseUrl],
+    [ContextSource.DEFAULT, DEFAULT_BASE_URL],
+  ]);
+  const storedPair = apiKeySource === ContextSource.PROFILE && baseUrlSource === ContextSource.PROFILE;
+  const requestedCustomBaseUrl =
+    typeof flags.allowCustomBaseUrl === 'boolean'
+      ? flags.allowCustomBaseUrl
+      : TRUTHY_ENV_VALUES.has(env[ALLOW_CUSTOM_BASE_URL_ENV]);
+  const allowCustomBaseUrl = customBaseUrlFromStoredProfileOnly ? storedPair : requestedCustomBaseUrl;
+  const baseUrl = normalizeResolvedBaseUrl({
+    value: rawBaseUrl,
+    source: baseUrlSource,
+    profileName: profile.name,
+    tolerateStored: !enforceAllowlist,
+    revealLocalDetails,
+  });
+  if (enforceAllowlist && baseUrlSource !== ContextSource.DEFAULT) {
+    const guidanceFor = customBaseUrlFromStoredProfileOnly ? storedProfileOnlyGuidance : allowlistGuidance;
+    assertAllowedBaseUrl(baseUrl, allowCustomBaseUrl, guidanceFor);
+  }
+
+  return {
+    apiKey,
+    baseUrl,
+    storedBaseUrl: profile.values.baseUrl,
+    profile: { name: profile.name, source: profile.source, explicit: profile.explicit, known: profile.known },
+    source: {
+      apiKey: apiKeySource,
+      baseUrl: baseUrlSource,
+      envIgnored: apiKeySource !== ContextSource.ENV && isSet(env[API_KEY_ENV]),
+      baseUrlEnvIgnored: baseUrlSource !== ContextSource.ENV && isSet(env[BASE_URL_ENV]),
+    },
+  };
+};
+
+export const loadContext = async (
+  flags = {},
+  { enforceAllowlist = true, allowUnknownProfile = false, customBaseUrlFromStoredProfileOnly = false } = {},
+) =>
+  resolveContext({
+    flags,
+    env: process.env,
+    config: await loadConfig(),
+    enforceAllowlist,
+    allowUnknownProfile,
+    customBaseUrlFromStoredProfileOnly,
+  });
+
+const renderCliReference = (spec, args) => {
+  const words = spec.id.split('.');
+  const positionals = (spec.cli?.positionals ?? []).map((field) => args[field]).filter((value) => value !== undefined);
+  const optionNames = Object.fromEntries(
+    Object.entries(spec.cli?.options ?? {}).map(([option, entry]) => [
+      typeof entry === 'string' ? entry : entry.field,
+      option,
+    ]),
+  );
+  const options = Object.entries(args)
+    .filter(([field, value]) => value !== undefined && !(spec.cli?.positionals ?? []).includes(field))
+    .map(([field, value]) => {
+      const option = optionNames[field] ?? field.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+      return value === true ? `--${option}` : `--${option} ${value}`;
+    });
+  return [CLI_BINARY, ...words, ...positionals, ...options].join(' ');
+};
+
+const toSnakeCase = (name) => name.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+
+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;
+  const toolArgs = Object.fromEntries(entries.map(([field, value]) => [toSnakeCase(field), value]));
+  return `${toolName} ${JSON.stringify(toolArgs)}`;
+};
+
+export const createCommandContext = ({
+  resolved,
+  registry,
+  surface,
+  signal,
+  cwd,
+  uploadDir,
+  usageGuidance,
+  timeouts = {},
+}) => {
+  const ctx = {
+    surface,
+    apiKey: resolved.apiKey,
+    baseUrl: resolved.baseUrl,
+    storedBaseUrl: resolved.storedBaseUrl,
+    profile: resolved.profile,
+    source: resolved.source,
+    signal,
+    cwd,
+    uploadDir,
+    usageGuidance,
+    longRunning: false,
+    ...timeouts,
+    request: (request) => requestAgentApi(ctx, request),
+    http: async (request) => (await requestAgentApi(ctx, request)).result,
+    ref: (id, args = {}) => {
+      const spec = registry.byId.get(id);
+      if (!spec) throw new Error(`ctx.ref: unknown command id ${id}`);
+      return surface === Surface.MCP ? renderMcpReference(spec, args) : renderCliReference(spec, args);
+    },
+  };
+  return ctx;
+};

package/src/core/errors.js

@@ -1,3 +1,25 @@
+import { redactSecrets } from './redact.js';
+
+export const CliErrorCode = Object.freeze({
+  AUTH_REQUIRED: 'CLI_AUTH_REQUIRED',
+  NETWORK_ERROR: 'CLI_NETWORK_ERROR',
+  NON_JSON_RESPONSE: 'CLI_NON_JSON_RESPONSE',
+  UPSTREAM_ERROR: 'CLI_UPSTREAM_ERROR',
+  INVALID_USAGE: 'CLI_INVALID_USAGE',
+  UNEXPECTED_ERROR: 'CLI_UNEXPECTED_ERROR',
+  OPERATION_MAY_STILL_BE_RUNNING: 'CLI_OPERATION_MAY_STILL_BE_RUNNING',
+  CONFIG_UNREADABLE: 'CLI_CONFIG_UNREADABLE',
+  CONFIG_UNWRITABLE: 'CLI_CONFIG_UNWRITABLE',
+});
+
+export const USAGE_GUIDANCE =
+  'Run the current command again with --help to see the required arguments and input format.';
+export const MCP_USAGE_GUIDANCE = 'Check the tool description and input schema, then call the tool again.';
+export const UNEXPECTED_ERROR_GUIDANCE =
+  'Retry with --help for usage details. If the command and inputs look correct, inspect the error details and ' +
+  'try again.';
+export const UNEXPECTED_ERROR_MESSAGE = 'Unexpected CLI failure.';
+
 export const cliError = (code, message, guidance, details) => ({
   ok: false,
   error: {
@@ -13,3 +35,20 @@ export const cliSuccess = (data, guidance) => ({
   data,
   agent_guidance: guidance,
 });
+
+export const codedError = (code, message, guidance, details) =>
+  Object.assign(new Error(message), { cliCode: code, guidance, ...(details ? { details } : {}) });
+
+export const usageError = (message, guidance = USAGE_GUIDANCE) =>
+  codedError(CliErrorCode.INVALID_USAGE, message, guidance);
+
+export const isEnvelope = (value) =>
+  Boolean(value) && typeof value === 'object' && !Array.isArray(value) && typeof value.ok === 'boolean';
+
+export const toErrorEnvelope = (error, { usageGuidance = USAGE_GUIDANCE } = {}) => {
+  const message = error?.message || UNEXPECTED_ERROR_MESSAGE;
+  const code = error?.cliCode || CliErrorCode.UNEXPECTED_ERROR;
+  const rawGuidance = error?.guidance || UNEXPECTED_ERROR_GUIDANCE;
+  const guidance = rawGuidance === USAGE_GUIDANCE ? usageGuidance : rawGuidance;
+  return cliError(code, redactSecrets(message), redactSecrets(guidance), error?.details);
+};

package/src/core/execute.js

@@ -0,0 +1,71 @@
+import { BODY_INPUT_NAME, BodyMode, JSON_BODY_MODES, assertEnvelope } from '../commands/registry.js';
+import { LONG_RUNNING_GATEWAY_STATUSES, Surface } from './constants.js';
+import { CliErrorCode, cliError, toErrorEnvelope } from './errors.js';
+import { validateInput } from './schema.js';
+
+const INTERRUPTED_DETAILS = Object.freeze(['timed_out', 'cancelled', 'outcome_unknown']);
+
+const stillRunningGuidance = (ctx, spec) =>
+  `The request did not complete, but the server may still be processing it. Do not retry; poll ${ctx.ref(
+    spec.longRunning.pollTool,
+  )} until the work shows up, then continue from there.`;
+
+const mayStillBeRunning = (ctx, spec, message, details) =>
+  cliError(CliErrorCode.OPERATION_MAY_STILL_BE_RUNNING, message, stillRunningGuidance(ctx, spec), details);
+
+const mapLongRunningResult = (spec, result, ctx) => {
+  if (!spec.longRunning || result.ok !== false) return result;
+  const status = result.error?.details?.status;
+  if (result.error?.code === CliErrorCode.UPSTREAM_ERROR && LONG_RUNNING_GATEWAY_STATUSES.includes(status)) {
+    return mayStillBeRunning(ctx, spec, result.error.message, result.error.details);
+  }
+  return result;
+};
+
+const mapLongRunningError = (spec, error, ctx) => {
+  const interrupted = INTERRUPTED_DETAILS.some((detail) => error?.details?.[detail] === true);
+  if (!spec.longRunning || error?.cliCode !== CliErrorCode.NETWORK_ERROR || !interrupted) return null;
+  return mayStillBeRunning(ctx, spec, error.message, error.details);
+};
+
+const splitBodyField = (fields) => {
+  const { [BODY_INPUT_NAME]: bodyField, ...rest } = fields;
+  return { bodyField, rest };
+};
+
+const resolveBody = async (spec, loadBody) => {
+  if (spec.body === BodyMode.NONE) return undefined;
+  if (spec.body === BodyMode.EMPTY_OBJECT) return {};
+  if (JSON_BODY_MODES.includes(spec.body)) return loadBody();
+  return spec.body;
+};
+
+const mergeBody = (spec, input, body) => {
+  if (!spec.bodyMerge || body === undefined) return body;
+  const merged = { ...body };
+  for (const [bodyKey, field] of Object.entries(spec.bodyMerge)) {
+    if (input[field] !== undefined) merged[bodyKey] = input[field];
+  }
+  return merged;
+};
+
+export const executeCommand = async ({ spec, raw, loadBody = async () => undefined, ctx, labels = {} }) => {
+  const validation = { ...labels, splitLists: ctx.surface !== Surface.MCP };
+  try {
+    const { bodyField, rest } = splitBodyField(spec.input);
+    const input = validateInput(rest, raw, validation);
+    const rawBody = await resolveBody(spec, loadBody);
+    if (bodyField) {
+      const validated = validateInput({ [BODY_INPUT_NAME]: bodyField }, { [BODY_INPUT_NAME]: rawBody }, validation);
+      if (BODY_INPUT_NAME in validated) input[BODY_INPUT_NAME] = mergeBody(spec, input, validated[BODY_INPUT_NAME]);
+    } else if (rawBody !== undefined) {
+      input[BODY_INPUT_NAME] = rawBody;
+    }
+    if (spec.refine) spec.refine(input, ctx);
+    ctx.longRunning = Boolean(spec.longRunning);
+    const result = assertEnvelope(spec, await spec.run(input, ctx));
+    return mapLongRunningResult(spec, result, ctx);
+  } catch (error) {
+    return mapLongRunningError(spec, error, ctx) ?? toErrorEnvelope(error, { usageGuidance: ctx.usageGuidance });
+  }
+};

package/src/core/files.js

@@ -0,0 +1,186 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { MAX_IMAGE_UPLOAD_BYTES } from './constants.js';
+import { usageError } from './errors.js';
+
+const ImageMime = Object.freeze({
+  JPEG: 'image/jpeg',
+  PNG: 'image/png',
+  WEBP: 'image/webp',
+  GIF: 'image/gif',
+});
+
+export const IMAGE_MIME_BY_EXTENSION = Object.freeze({
+  '.jpg': ImageMime.JPEG,
+  '.jpeg': ImageMime.JPEG,
+  '.png': ImageMime.PNG,
+  '.webp': ImageMime.WEBP,
+  '.gif': ImageMime.GIF,
+});
+
+const SUPPORTED_EXTENSIONS_TEXT = 'Use one of: .jpg, .jpeg, .png, .webp, .gif.';
+const SNIFF_LENGTH = 12;
+const WEBP_RIFF_OFFSET = 8;
+
+const MAGIC_SIGNATURES = Object.freeze({
+  [ImageMime.PNG]: [{ offset: 0, bytes: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a] }],
+  [ImageMime.JPEG]: [{ offset: 0, bytes: [0xff, 0xd8, 0xff] }],
+  [ImageMime.GIF]: [
+    { offset: 0, bytes: [0x47, 0x49, 0x46, 0x38, 0x37, 0x61] },
+    { offset: 0, bytes: [0x47, 0x49, 0x46, 0x38, 0x39, 0x61] },
+  ],
+  [ImageMime.WEBP]: [
+    { offset: 0, bytes: [0x52, 0x49, 0x46, 0x46], then: { offset: WEBP_RIFF_OFFSET, bytes: [0x57, 0x45, 0x42, 0x50] } },
+  ],
+});
+
+const matchesAt = (buffer, { offset, bytes }) =>
+  buffer.length >= offset + bytes.length && bytes.every((byte, index) => buffer[offset + index] === byte);
+
+const matchesSignature = (buffer, signature) =>
+  matchesAt(buffer, signature) && (signature.then === undefined || matchesAt(buffer, signature.then));
+
+export const sniffImageMime = (buffer) => {
+  const head = buffer.subarray(0, SNIFF_LENGTH);
+  for (const [mime, signatures] of Object.entries(MAGIC_SIGNATURES)) {
+    if (signatures.some((signature) => matchesSignature(head, signature))) return mime;
+  }
+  return undefined;
+};
+
+const readGuidance = (absolutePath) => `Confirm that ${absolutePath} exists and is readable, then retry.`;
+const OUTSIDE_GUIDANCE = 'Move or copy the image into the allowed upload directory, then pass its path again.';
+const OVERSIZE_GUIDANCE = 'Resize or compress the image below the limit, then retry.';
+const FILE_NAME_GUIDANCE = 'Rename the file using letters, digits, dots, dashes, underscores or spaces, then retry.';
+const PARENT_SEGMENT = '..';
+const MAX_FILE_NAME_LENGTH = 255;
+const FIRST_PRINTABLE_CODE = 0x20;
+const DELETE_CODE = 0x7f;
+
+const isInside = (directory, target) => {
+  const relative = path.relative(directory, target);
+  if (relative === '' || relative === PARENT_SEGMENT || path.isAbsolute(relative)) return false;
+  return !relative.startsWith(`${PARENT_SEGMENT}${path.sep}`);
+};
+
+const outsideError = (allowedDir) => usageError(`The file must be inside ${allowedDir}.`, OUTSIDE_GUIDANCE);
+
+const oversizeError = (subject, size) =>
+  usageError(
+    `${subject} is ${size} bytes; the maximum upload size is ${MAX_IMAGE_UPLOAD_BYTES} bytes.`,
+    OVERSIZE_GUIDANCE,
+  );
+
+const hasControlCharacter = (text) =>
+  [...text].some((character) => {
+    const code = character.codePointAt(0);
+    return code < FIRST_PRINTABLE_CODE || code === DELETE_CODE;
+  });
+
+const assertSafeFileName = (fileName) => {
+  if (fileName.length > MAX_FILE_NAME_LENGTH || hasControlCharacter(fileName)) {
+    throw usageError('The image file name is too long or contains control characters.', FILE_NAME_GUIDANCE);
+  }
+};
+
+const toUpload = (buffer, fileName) => {
+  assertSafeFileName(fileName);
+  const extension = path.extname(fileName).toLowerCase();
+  const fileType = IMAGE_MIME_BY_EXTENSION[extension];
+  if (!fileType) {
+    throw usageError(`Unsupported image file extension: ${extension || '(none)'}.`, SUPPORTED_EXTENSIONS_TEXT);
+  }
+  const sniffed = sniffImageMime(buffer);
+  if (sniffed !== fileType) {
+    throw usageError(
+      `The file content does not look like ${fileType}${sniffed ? ` (detected ${sniffed})` : ''}: ${fileName}`,
+      'Make sure the file is a real image whose bytes match its extension, then retry.',
+    );
+  }
+  return { file_base64: buffer.toString('base64'), file_name: fileName, file_type: fileType };
+};
+
+export const readImageUploadFromBase64 = ({ base64, fileName }) => {
+  if (typeof base64 !== 'string' || base64 === '' || typeof fileName !== 'string' || fileName === '') {
+    throw usageError('An image upload needs file_base64 and file_name.', 'Pass both fields, or a file path instead.');
+  }
+  const buffer = Buffer.from(base64, 'base64');
+  if (buffer.length === 0 || buffer.toString('base64').replace(/=+$/, '') !== base64.replace(/=+$/, '')) {
+    throw usageError('file_base64 is not valid base64.', 'Encode the image bytes as standard base64, then retry.');
+  }
+  if (buffer.length > MAX_IMAGE_UPLOAD_BYTES) throw oversizeError('The image', buffer.length);
+  return toUpload(buffer, path.basename(fileName));
+};
+
+const resolveAllowedDir = async (allowedDir) => {
+  if (allowedDir === undefined) return undefined;
+  return { lexical: path.resolve(allowedDir), real: await fs.realpath(allowedDir), shown: allowedDir };
+};
+
+const assertLexicallyInside = (filePath, allowed) => {
+  if (allowed === undefined) return;
+  const target = path.resolve(filePath);
+  if (!isInside(allowed.lexical, target) && !isInside(allowed.real, target)) throw outsideError(allowed.shown);
+};
+
+const resolveReadPath = async (filePath, allowed) => {
+  if (allowed === undefined) return filePath;
+  const realFile = await fs.realpath(filePath);
+  if (!isInside(allowed.real, realFile)) throw outsideError(allowed.shown);
+  return realFile;
+};
+
+const readOpenedFile = async (readPath) => {
+  const handle = await fs.open(readPath, 'r');
+  try {
+    const stats = await handle.stat();
+    if (!stats.isFile()) throw usageError(`Not a file: ${readPath}`, readGuidance(readPath));
+    if (stats.size > MAX_IMAGE_UPLOAD_BYTES) throw oversizeError('The file', stats.size);
+    return await handle.readFile();
+  } finally {
+    await handle.close();
+  }
+};
+
+export const readImageUpload = async ({ filePath, allowedDir }) => {
+  if (typeof filePath !== 'string' || filePath === '') {
+    throw usageError('Missing required option: --file <path>.', 'Pass a local image path with `--file <path>`.');
+  }
+  if (!path.isAbsolute(filePath)) {
+    throw usageError(`The file path must be absolute: ${filePath}`, 'Resolve the path before passing it.');
+  }
+  const allowed = await resolveAllowedDir(allowedDir);
+  assertLexicallyInside(filePath, allowed);
+
+  let readPath;
+  let stats;
+  try {
+    readPath = await resolveReadPath(filePath, allowed);
+    stats = await fs.stat(readPath);
+  } catch (error) {
+    if (error?.cliCode) throw error;
+    throw usageError(`Failed to read file: ${error.message}`, readGuidance(filePath));
+  }
+  if (!stats.isFile()) {
+    throw usageError(`Not a file: ${filePath}`, readGuidance(filePath));
+  }
+  if (stats.size > MAX_IMAGE_UPLOAD_BYTES) throw oversizeError('The file', stats.size);
+
+  const fileName = path.basename(filePath);
+  const extension = path.extname(fileName).toLowerCase();
+  if (!IMAGE_MIME_BY_EXTENSION[extension]) {
+    throw usageError(`Unsupported image file extension: ${extension || '(none)'}.`, SUPPORTED_EXTENSIONS_TEXT);
+  }
+
+  let buffer;
+  try {
+    buffer = await readOpenedFile(readPath);
+  } catch (error) {
+    if (error?.cliCode) throw error;
+    throw usageError(`Failed to read file: ${error.message}`, readGuidance(filePath));
+  }
+  if (buffer.length > MAX_IMAGE_UPLOAD_BYTES) throw oversizeError('The file', buffer.length);
+
+  return toUpload(buffer, fileName);
+};