{"record":{"id":"e5405f8254e0eb35","repo":"jackwener/OpenCLI","slug":"lichess-username-is-required","errorCode":null,"errorMessage":"lichess username is required","messagePattern":"lichess username is required","errorType":"validation","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"clis/lichess/utils.js","lineNumber":24,"sourceCode":"import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';\n\nexport const LICHESS_BASE = 'https://lichess.org';\nconst UA = 'opencli-lichess-adapter/1.0 (+https://github.com/jackwener/opencli; mailto:opencli@example.com)';\n\n// Lichess usernames are 2-30 chars: letters, digits, underscore, dash. Case-insensitive.\nconst USERNAME_PATTERN = /^[A-Za-z0-9_-]{2,30}$/;\n\n// `perfType` values lichess accepts for the `/api/player/top/<n>/<perf>` endpoint.\n// Source: lichess-org/api docs.\nexport const LICHESS_PERFS = new Set([\n    'ultraBullet', 'bullet', 'blitz', 'rapid', 'classical',\n    'chess960', 'crazyhouse', 'antichess', 'atomic', 'horde',\n    'kingOfTheHill', 'racingKings', 'threeCheck',\n]);\n\nexport function requireUsername(value) {\n    const raw = String(value ?? '').trim();\n    if (!raw) throw new ArgumentError('lichess username is required');\n    if (!USERNAME_PATTERN.test(raw)) {\n        throw new ArgumentError(\n            `lichess username \"${value}\" is not a valid handle`,\n            'Allowed: letters, digits, underscore, dash; length 2-30.',\n        );\n    }\n    return raw;\n}\n\nexport function requirePerf(value) {\n    const raw = String(value ?? '').trim();\n    if (!raw) throw new ArgumentError('lichess perf is required (e.g. \"blitz\", \"bullet\", \"rapid\")');\n    if (!LICHESS_PERFS.has(raw)) {\n        throw new ArgumentError(\n            `lichess perf \"${value}\" is not recognised`,\n            `Allowed values: ${[...LICHESS_PERFS].join(', ')}.`,\n        );\n    }","sourceCodeStart":6,"sourceCodeEnd":42,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/lichess/utils.js#L6-L42","documentation":"This ArgumentError is thrown by `requireUsername` when the username argument is missing, empty, or only whitespace after `String(value ?? '').trim()`. The library requires a non-empty handle before making any Lichess API call.","triggerScenarios":"Calling `username()` (or any command routed through `requireUsername`) with `undefined`, `null`, `''`, or a whitespace-only string for the username parameter.","commonSituations":"Forgetting the CLI positional argument; an env-var or config value that resolves to empty; scripting where a variable was never set; shell quoting issues yielding an empty string.","solutions":["Pass a non-empty username to the command/argument","Check the value before calling: trim it and verify it is truthy","Fix the source of the empty value (env var, config key, script variable)","Use `--help` to confirm the command's expected argument order"],"exampleFix":"// before\nawait username(''); // ArgumentError: lichess username is required\n// after\nconst name = process.env.PLAYER?.trim();\nif (!name) throw new Error('PLAYER env var must be set');\nawait username(name);","handlingStrategy":"validation","validationCode":"function assertUsernameProvided(v) {\n  const s = String(v ?? '').trim();\n  if (!s) throw new TypeError('username is required');\n  return s;\n}\nassertUsernameProvided(cliArgs.username);","typeGuard":"function hasUsername(v) {\n  return typeof v === 'string' && v.trim().length > 0;\n}","tryCatchPattern":"try {\n  await username(args[0]);\n} catch (e) {\n  if (e instanceof ArgumentError && /username is required/.test(e.message)) {\n    console.error('Usage: lichess user <username>');\n    process.exitCode = 2;\n  } else throw e;\n}","preventionTips":["Always pass an explicit positional username; never rely on unset vars","Trim inputs from env/config before passing","Add a CLI usage check that errors before invoking the API","Default prompt for the username in interactive wrappers"],"tags":["lichess","argument-validation","missing-argument"],"backgroundTag":"missing-required-argument","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}