{"record":{"id":"2c1fc309330c7e70","repo":"jackwener/OpenCLI","slug":"flathub-label-must-be-maxvalue","errorCode":null,"errorMessage":"flathub ${label} must be <= ${maxValue}","messagePattern":"flathub (.+?) must be <= (.+?)","errorType":"validation","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"clis/flathub/utils.js","lineNumber":30,"sourceCode":"\n// AppStream IDs are reverse-DNS (e.g. \"org.gnome.Calculator\"); the spec allows\n// letters, digits, `.`, `_`, `-`. Min two segments separated by `.`.\nconst APP_ID_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*(?:\\.[A-Za-z0-9_][A-Za-z0-9_-]*){1,}$/;\n\nexport function requireString(value, label) {\n    const s = String(value ?? '').trim();\n    if (!s) throw new ArgumentError(`flathub ${label} cannot be empty`);\n    return s;\n}\n\nexport function requireBoundedInt(value, defaultValue, maxValue, label = 'limit') {\n    const raw = value ?? defaultValue;\n    const n = typeof raw === 'number' ? raw : Number(raw);\n    if (!Number.isInteger(n) || n <= 0) {\n        throw new ArgumentError(`flathub ${label} must be a positive integer`);\n    }\n    if (n > maxValue) {\n        throw new ArgumentError(`flathub ${label} must be <= ${maxValue}`);\n    }\n    return n;\n}\n\nexport function requireAppId(value) {\n    const raw = String(value ?? '').trim();\n    if (!raw) throw new ArgumentError('flathub appId is required (e.g. \"org.mozilla.firefox\")');\n    if (!APP_ID_PATTERN.test(raw)) {\n        throw new ArgumentError(\n            `flathub appId \"${value}\" is not a valid AppStream identifier`,\n            'AppStream IDs use reverse-DNS like \"org.mozilla.firefox\" — letters/digits/`._-` with at least one dot.',\n        );\n    }\n    return raw;\n}\n\nexport async function flathubFetch(url, label, init) {\n    let resp;","sourceCodeStart":12,"sourceCodeEnd":48,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/flathub/utils.js#L12-L48","documentation":"requireBoundedInt enforces an upper bound on a numeric option (labelled, default 'limit'); it throws ArgumentError with 'flathub <label> must be <= <maxValue>' when the value is a positive integer but exceeds the adapter's allowed maximum. This keeps requests within sensible API page sizes.","triggerScenarios":"Calling requireBoundedInt(value, defaultValue, maxValue, label) with a value greater than maxValue, e.g. requireBoundedInt(100, 10, 50) or a CLI invocation like `flathub search foo --limit 200` when the cap is 50.","commonSituations":"Users asking for very large result sets (e.g. --limit 1000); scripting with an unbounded page size; copying a limit from another API with a higher cap; misreading the documented maximum.","solutions":["Lower the value to at most the stated maximum (the error message tells you the cap)","Omit the option to use the default limit","Paginate: fetch multiple pages instead of one oversized request","Clamp in your script: limit = Math.min(requested, maxAllowed)"],"exampleFix":"// before\nawait searchApps(query, { limit: 200 }); // max is 50\n// after\nawait searchApps(query, { limit: Math.min(200, 50) });","handlingStrategy":"validation","validationCode":"const MAX_LIMIT = 50;\nconst limit = Math.min(Number(opts.limit ?? 10), MAX_LIMIT);\nif (!Number.isInteger(limit) || limit <= 0) throw new Error('limit must be a positive integer');","typeGuard":"function isWithinBounds(v, max) {\n  const n = typeof v === 'number' ? v : Number(v);\n  return Number.isInteger(n) && n > 0 && n <= max;\n}","tryCatchPattern":"try {\n  await searchApps(query, { limit });\n} catch (err) {\n  if (err instanceof ArgumentError && /must be <=/.test(err.message)) {\n    console.error(err.message + ' — lower the limit or paginate');\n    process.exitCode = 2;\n  } else throw err;\n}","preventionTips":["Clamp user-supplied limits to the documented maximum before calling","Check the adapter docs/source for the maxValue passed to requireBoundedInt","Paginate with repeated smaller requests instead of one oversized limit","Enforce caps at the CLI-parser level (e.g. commander .argParser with Math.min)"],"tags":["argument-validation","input-error","bounds-check"],"backgroundTag":"invalid-argument-value","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}