Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
2.5 KB
Raw Blame
/**
 * Agent contract v1 (D4): strict numeric values for CLI-only command flags.
 * A malformed, out-of-range or missing value is a usage error
 * (`invalid_params`, exit 2 through renderCliError) naming the flag, what it
 * accepts and a valid example, instead of a silent NaN/parseInt fallback.
 * Absorbs the community numeric-flag fixes (#5936 #5934 #5933 #5931 #5930
 * #5909) behind one rule set.
 */
import { inertText } from '../core/agent-output.ts';
import type { OperationError } from '../core/ops/contract.ts';
import { usageError } from './cli-error.ts';

export interface NumericFlagRule {
  min?: number;
  max?: number;
  /** A valid value for the suggestion. */
  example: number;
}

function requirement(kind: 'integer' | 'number', r: NumericFlagRule): string {
  if (r.min !== undefined && r.max !== undefined) return `${kind === 'integer' ? 'an integer' : 'a number'} from ${r.min} to ${r.max}`;
  if (r.min === 1 && kind === 'integer') return 'a positive integer';
  if (r.min === 0) return `a non-negative ${kind}`;
  return kind === 'integer' ? 'an integer' : 'a finite number';
}

/** The usage error for a bad flag value (also used by commands with their own rules). */
export function flagValueError(flag: string, raw: string | undefined, accepts: string, example: number | string): OperationError {
  const missing = raw === undefined || raw.trim() === '' || raw.startsWith('--');
  return usageError(
    missing ? `${flag} requires a value: ${accepts}.` : `${flag} must be ${accepts}; got '${inertText(raw, 40)}'.`,
    `Pass ${accepts}, e.g. ${flag} ${example}.`,
  );
}

/** Digits only (a leading sign when negatives are allowed), a safe integer, within [min, max]. */
export function intFlagValue(raw: string | undefined, flag: string, rule: NumericFlagRule): number {
  const text = raw?.trim() ?? '';
  const signed = rule.min === undefined || rule.min < 0;
  const n = Number(text);
  if ((signed ? /^[+-]?\d+$/ : /^\+?\d+$/).test(text) && Number.isSafeInteger(n)
    && n >= (rule.min ?? -Infinity) && n <= (rule.max ?? Infinity)) return n;
  throw flagValueError(flag, raw, requirement('integer', rule), rule.example);
}

/** A finite number within [min, max]. */
export function numberFlagValue(raw: string | undefined, flag: string, rule: NumericFlagRule): number {
  const text = raw?.trim() ?? '';
  const n = Number(text);
  if (text !== '' && Number.isFinite(n) && n >= (rule.min ?? -Infinity) && n <= (rule.max ?? Infinity)) return n;
  throw flagValueError(flag, raw, requirement('number', rule), rule.example);
}