{"record":{"id":"5376b0fe5665f2a7","repo":"jackwener/OpenCLI","slug":"label-must-be-a-numeric-id","errorCode":null,"errorMessage":"${label} must be a numeric ID","messagePattern":"(.+?) must be a numeric ID","errorType":"validation","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"clis/_shared/common.js","lineNumber":22,"sourceCode":"import { ArgumentError } from '@jackwener/opencli/errors';\n/**\n * Clamp a numeric value to [min, max].\n * Matches the signature of lodash.clamp and Rust's clamp.\n */\nexport function clamp(value, min, max) {\n    return Math.max(min, Math.min(value, max));\n}\nexport function clampInt(raw, fallback, min, max) {\n    const parsed = Number(raw);\n    if (!Number.isFinite(parsed)) {\n        return fallback;\n    }\n    return clamp(Math.floor(parsed), min, max);\n}\nexport function normalizeNumericId(value, label, example) {\n    const normalized = String(value ?? '').trim();\n    if (!/^\\d+$/.test(normalized)) {\n        throw new ArgumentError(`${label} must be a numeric ID`, `Pass a numeric ${label}, for example: ${example}`);\n    }\n    return normalized;\n}\nexport function requireNonEmptyQuery(value, label = 'query') {\n    const normalized = String(value ?? '').trim();\n    if (!normalized) {\n        throw new ArgumentError(`${label} cannot be empty`);\n    }\n    return normalized;\n}\n","sourceCodeStart":4,"sourceCodeEnd":33,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/_shared/common.js#L4-L33","documentation":"normalizeNumericId validates that a value (issue/page ID) is a string of digits only. Anything else — alphanumeric keys, undefined, objects, negative numbers, floats — throws ArgumentError '<label> must be a numeric ID' with a usage hint including an example.","triggerScenarios":"Calling normalizeNumericId (or a CLI flag routed through it) with a human-readable key like 'PROJ-123', 'ABC123', an empty string, undefined, a negative or decimal number, or an object.","commonSituations":"Passing an issue KEY (PROJ-123) where a numeric issue ID is required; pasting an ID with whitespace plus stray characters; passing null/undefined because an earlier lookup failed; passing a float like 12345.0 from JSON config.","solutions":["Look up the numeric ID (e.g. via the corresponding get/search command) and pass digits only, e.g. 10001 not PROJ-123.","Trim and sanitize the value before calling; ensure it matches /^\\d+$/.","Fix the upstream code path returning null/undefined so a real ID reaches the call."],"exampleFix":"// before\nnormalizeNumericId('PROJ-123', 'issue ID', '12345')\n// after\nnormalizeNumericId('12345', 'issue ID', '12345')","handlingStrategy":"validation","validationCode":"const id = String(value ?? '').trim();\nif (!/^\\d+$/.test(id)) throw new Error(`${label} must be numeric digits, got: ${value}`);","typeGuard":"const isNumericId = (v) => typeof v !== 'object' && /^\\d+$/.test(String(v ?? '').trim());","tryCatchPattern":"try {\n  const id = normalizeNumericId(input, 'issue ID', '12345');\n} catch (err) {\n  if (err.name === 'ArgumentError' && err.message.includes('numeric ID')) {\n    console.error('Pass the numeric ID (e.g. 12345), not the issue key (e.g. PROJ-123).');\n  }\n  throw err;\n}","preventionTips":["Resolve issue keys (PROJ-123) to numeric IDs via the API before write operations.","Validate IDs with /^\\d+$/ at config-load time.","Fail fast when an upstream lookup returns null/undefined instead of passing it downstream."],"tags":["validation","argument-validation","numeric-id","cli"],"backgroundTag":"invalid-id-format","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}