jackwener/OpenCLI · error · ArgumentError

homebrew ${label} must be a positive integer

Error message

homebrew ${label} must be a positive integer

What it means

requireBoundedInt coerces its input to a number and throws ArgumentError('homebrew <label> must be a positive integer') when the value is not an integer or is <= 0. It protects numeric options like limit from non-numeric or non-positive input.

Source

Thrown at clis/homebrew/utils.js:26

export const BREW_BASE = 'https://formulae.brew.sh/api';
const UA = 'opencli-homebrew-adapter (+https://github.com/jackwener/opencli)';

// Homebrew formula / cask tokens — letters / digits / `_-.+@` (`gcc@13`,
// `imagemagick@6`, `c++`, `0-ad`, `php-cs-fixer`).
const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._+@-]*$/;

export function requireString(value, label) {
    const s = String(value ?? '').trim();
    if (!s) throw new ArgumentError(`homebrew ${label} cannot be empty`);
    return s;
}

export function requireBoundedInt(value, defaultValue, maxValue, label = 'limit') {
    const raw = value ?? defaultValue;
    const n = typeof raw === 'number' ? raw : Number(raw);
    if (!Number.isInteger(n) || n <= 0) {
        throw new ArgumentError(`homebrew ${label} must be a positive integer`);
    }
    if (n > maxValue) {
        throw new ArgumentError(`homebrew ${label} must be <= ${maxValue}`);
    }
    return n;
}

export function requireToken(value, label) {
    const s = String(value ?? '').trim();
    if (!s) {
        throw new ArgumentError(`homebrew ${label} is required (e.g. "wget", "gcc@13", "firefox")`);
    }
    if (s.length > 100 || !TOKEN.test(s)) {
        throw new ArgumentError(
            `homebrew ${label} "${value}" is not a valid token`,
            'Use letters / digits / "_-.+@", starting with a letter or digit (max 100 chars).',
        );
    }

View on GitHub (pinned to 49907e53dc)

Solutions

  1. Provide a positive whole number for the option (e.g. --limit 30)
  2. Omit the option entirely to use the default (e.g. 30)
  3. Coerce/validate the value with Number.isInteger before calling
  4. Catch ArgumentError and print usage showing accepted range

Example fix

// before
const limit = args.limit || '';
// after
const n = Number(args.limit);
if (!Number.isInteger(n) || n <= 0) throw new Error('--limit must be a positive integer');
Defensive patterns

Strategy: validation

Validate before calling

function parsePositiveInt(raw) {
  const n = typeof raw === 'number' ? raw : Number(raw);
  if (!Number.isInteger(n) || n <= 0) {
    throw new Error(`limit must be a positive integer, got ${JSON.stringify(raw)}`);
  }
  return n;
}

Type guard

function isPositiveInt(v) {
  return typeof v === 'number' && Number.isInteger(v) && v > 0;
}

Try / catch

try {
  await homebrewPopular({ limit: rawLimit });
} catch (err) {
  if (err instanceof ArgumentError && /positive integer/.test(err.message)) {
    console.error('--limit must be a whole number > 0');
    process.exitCode = 2;
    return;
  }
  throw err;
}

Prevention

When it happens

Trigger: Passing --limit abc, --limit 0, --limit -5, --limit 3.5, or an empty string that coerces to NaN.

Common situations: Typo in a CLI flag value, users expecting 'all' or 'max' as a valid limit, scripts interpolating unset variables into the flag.

Understand the failure class

Background: Invalid argument type errors: "must be of type string", "expected X, got Y", and ERR_INVALID_ARG_TYPE explained — this error's family across 15 libraries.

Related errors

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/68c4156f0adee411. Report an issue: GitHub.