{"record":{"id":"8b1b849522ac2356","repo":"jackwener/OpenCLI","slug":"command-key-sitesession-must-be-one-of-ephemer","errorCode":null,"errorMessage":"Command ${key} siteSession must be one of: ephemeral, persistent","messagePattern":"Command (.+?) siteSession must be one of: ephemeral, persistent","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/registry.ts","lineNumber":218,"sourceCode":"    }\n  }\n\n  return browser\n    ? { ...cmd, strategy, browser: true, navigateBefore } as BrowserCliCommand\n    : { ...cmd, strategy, browser: false, navigateBefore } as NonBrowserCliCommand;\n}\n\nfunction assertCommandAccess(cmd: Pick<RawCliCommand, 'site' | 'name'> & { access?: unknown }): asserts cmd is RawCliCommand {\n  if (cmd.access === 'read' || cmd.access === 'write') return;\n  const key = `${cmd.site}/${cmd.name}`;\n  throw new Error(`Command ${key} must declare access: 'read' | 'write'`);\n}\n\nfunction assertSiteSession(cmd: Pick<RawCliCommand, 'site' | 'name'> & { siteSession?: unknown }): void {\n  if (cmd.siteSession === undefined) return;\n  const key = `${cmd.site}/${cmd.name}`;\n  if (cmd.siteSession !== 'ephemeral' && cmd.siteSession !== 'persistent') {\n    throw new Error(`Command ${key} siteSession must be one of: ephemeral, persistent`);\n  }\n}\n\nexport function registerCommand(cmd: RawCliCommand): void {\n  const normalized = normalizeCommand(cmd);\n  const canonicalKey = fullName(normalized);\n  const existing = _registry.get(canonicalKey);\n  if (existing?.aliases) {\n    for (const alias of existing.aliases) {\n      _registry.delete(`${existing.site}/${alias}`);\n    }\n  }\n\n  const aliases = normalizeAliases(normalized.aliases, normalized.name);\n  normalized.aliases = aliases.length > 0 ? aliases : undefined;\n  _registry.set(canonicalKey, normalized);\n  for (const alias of aliases) {\n    _registry.set(`${normalized.site}/${alias}`, normalized);","sourceCodeStart":200,"sourceCodeEnd":236,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/src/registry.ts#L200-L236","documentation":"assertSiteSession validates the optional siteSession property on a registered command: when present it must be exactly 'ephemeral' or 'persistent'. These values control how the CLI manages site sessions for the command, so any other value is rejected at registration time via normalizeCommand.","triggerScenarios":"Calling registerCommand(cmd) with cmd.siteSession defined but not 'ephemeral' or 'persistent' — e.g. siteSession: true, 'none', 'temporary', or 'Ephemeral' (case-sensitive). Omitting the property entirely is allowed.","commonSituations":"Typo or wrong-case value in a new command definition; copying a boolean-ish flag from another config; inventing a third session mode the library doesn't support.","solutions":["Set siteSession to exactly 'ephemeral' or 'persistent', or remove the property if no session behavior is needed.","Fix casing — the comparison is strict, 'Ephemeral' fails.","If a different session mode seems needed, check the library docs; only the two values are supported.","Add a schema/config lint step for command definitions to catch invalid enum values before registration."],"exampleFix":"// before\nregisterCommand({ site: \"jira\", name: \"login\", access: \"write\", siteSession: \"temporary\" });\n// after\nregisterCommand({ site: \"jira\", name: \"login\", access: \"write\", siteSession: \"persistent\" });","handlingStrategy":"type-guard","validationCode":"type SiteSession = \"ephemeral\" | \"persistent\";\nfunction hasValidSiteSession(cmd: { siteSession?: unknown }): boolean {\n  return cmd.siteSession === undefined || cmd.siteSession === \"ephemeral\" || cmd.siteSession === \"persistent\";\n}\nif (hasValidSiteSession(cmd)) registerCommand(cmd);","typeGuard":"function hasSiteSession(cmd: { siteSession?: unknown }): cmd is { siteSession: \"ephemeral\" | \"persistent\" } {\n  return cmd.siteSession === \"ephemeral\" || cmd.siteSession === \"persistent\";\n}","tryCatchPattern":"try {\n  registerCommand(cmd);\n} catch (e) {\n  if (e instanceof Error && e.message.includes(\"siteSession must be one of\")) {\n    console.error(`Bad siteSession on ${cmd.site}/${cmd.name}: use 'ephemeral' or 'persistent'`);\n  } else throw e;\n}","preventionTips":["Type siteSession as the union 'ephemeral' | 'persistent' (| undefined) in definitions.","Omit the property entirely when no session behavior is needed.","Watch for casing — enum values are lowercase and case-sensitive.","Add a schema validation (e.g. zod) over command config files before registration."],"tags":["registry","validation","command","enum"],"backgroundTag":"invalid-enum-value","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}