{"record":{"id":"7169a5003ac8156b","repo":"jackwener/OpenCLI","slug":"name-must-be-suffix-got-raw","errorCode":null,"errorMessage":"${name} must be${suffix} (got \"${raw}\")","messagePattern":"(.+?) must be(.+?) \\(got \"(.+?)\"\\)","errorType":"validation","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"clis/slock/resolve.js","lineNumber":53,"sourceCode":"const SHORT_ID_HINT =\n  'short ids (the 8-hex `msg=...` form in channel headers) are NOT accepted — use the FULL UUID ' +\n  'from `bookmark-list` / `message-read` output.';\n\nexport function assertMessageIdShape(messageId) {\n  const v = String(messageId ?? '').trim();\n  if (!v) throw new ArgumentError('messageId required');\n  if (!UUID_RE.test(v)) {\n    throw new ArgumentError(`messageId \"${v}\" is not a full UUID. ${SHORT_ID_HINT}`);\n  }\n  return v;\n}\n\nexport function parsePositiveInteger(value, name, { defaultValue, max } = {}) {\n  const raw = value === undefined || value === null || value === '' ? defaultValue : value;\n  const n = parseStrictInteger(raw);\n  if (!Number.isInteger(n) || n <= 0 || (max !== undefined && n > max)) {\n    const suffix = max !== undefined ? ` between 1 and ${max}` : ' as a positive integer';\n    throw new ArgumentError(`${name} must be${suffix} (got \"${raw}\")`);\n  }\n  return n;\n}\n\nexport function parseNonNegativeInteger(value, name, { defaultValue } = {}) {\n  const raw = value === undefined || value === null || value === '' ? defaultValue : value;\n  const n = parseStrictInteger(raw);\n  if (!Number.isInteger(n) || n < 0) {\n    throw new ArgumentError(`${name} must be a non-negative integer (got \"${raw}\")`);\n  }\n  return n;\n}\n\nfunction parseStrictInteger(raw) {\n  if (typeof raw === 'number')\n    return raw;\n  const text = String(raw);\n  if (!/^\\d+$/.test(text))","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/slock/resolve.js#L35-L71","documentation":"parsePositiveInteger validates a CLI numeric option and throws ArgumentError when the parsed value is not a strictly positive integer or exceeds the configured `max`. The message names the option, the allowed range, and echoes the raw input. It is the shared numeric-argument gate used by `limit` and `number` style options.","triggerScenarios":"Calling a CLI command with a limit/number option set to a non-integer (e.g. '3.5', 'abc'), zero, a negative number, or a value above the max passed in options (e.g. --limit 500 when max=100).","commonSituations":"Typing `--limit 0` expecting 'unlimited'; pasting a float like `--limit 2.5`; exceeding an API-imposed page-size cap; shell interpolation substituting an empty or garbage value into the flag.","solutions":["Pass a whole number >= 1 that does not exceed the option's documented max.","Omit the option entirely so the built-in defaultValue is used.","If you control the code, widen validation by using parseNonNegativeInteger or lowering the max constraint as appropriate."],"exampleFix":"// before\nawait cli('slock', 'task-list', '--limit', '2.5');\n// after\nawait cli('slock', 'task-list', '--limit', '25');","handlingStrategy":"validation","validationCode":"function isValidPositiveInt(v, max) {\n  const n = Number(v);\n  return Number.isInteger(n) && n >= 1 && (max === undefined || n <= max);\n}\nif (!isValidPositiveInt(limit, 100)) throw new Error('limit must be an integer 1..100');","typeGuard":"const isPositiveInt = (v) => typeof v === 'number' && Number.isInteger(v) && v > 0;","tryCatchPattern":"try {\n  runCommand(['--limit', String(raw)]);\n} catch (e) {\n  if (e instanceof ArgumentError && e.message.includes('must be')) {\n    console.error(`Bad --limit value \"${raw}\": ${e.message}`);\n    process.exitCode = 2;\n  } else throw e;\n}","preventionTips":["Clamp user-supplied limits into [1, max] before passing them on.","Never pass raw strings/floats into integer options; coerce and check Number.isInteger first.","Treat 0 or negative page sizes as a bug and clamp to 1."],"tags":["cli","argument-validation","input-parsing"],"backgroundTag":"invalid-argument-value","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}