@foundation0/git 1.3.0 → 1.3.2

package/src/label-management.ts

@@ -1,587 +1,587 @@
-import type { GitServiceApi, GitServiceApiExecutionResult, GitServiceApiMethod } from './git-service-api'
-
-const LABEL_LIST_PAGE_SIZE = 100
-const MAX_LABEL_LIST_PAGES = 100
-
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null && !Array.isArray(value)
-
-const toTrimmedString = (value: unknown): string | null => {
-  if (typeof value !== 'string') {
-    return null
-  }
-  const trimmed = value.trim()
-  return trimmed.length > 0 ? trimmed : null
-}
-
-const toPositiveInteger = (value: unknown): number | null => {
-  const candidate = Number(value)
-  if (!Number.isFinite(candidate) || candidate <= 0 || Math.floor(candidate) !== candidate) {
-    return null
-  }
-  return candidate
-}
-
-const toBoolean = (value: unknown, fallback: boolean): boolean => {
-  if (typeof value === 'boolean') {
-    return value
-  }
-
-  if (typeof value === 'string') {
-    const normalized = value.trim().toLowerCase()
-    if (normalized === 'true' || normalized === '1' || normalized === 'yes') {
-      return true
-    }
-    if (normalized === 'false' || normalized === '0' || normalized === 'no') {
-      return false
-    }
-  }
-
-  return fallback
-}
-
-const toQueryRecord = (raw: unknown): Record<string, string | number | boolean> => {
-  if (!isRecord(raw)) {
-    return {}
-  }
-
-  const query: Record<string, string | number | boolean> = {}
-  for (const [key, value] of Object.entries(raw)) {
-    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
-      query[key] = value
-    }
-  }
-  return query
-}
-
-type ScopeArgs = {
-  owner?: string
-  repo?: string
-  options: Record<string, unknown>
-}
-
-type NamedScopeArgs = ScopeArgs & {
-  name: string
-}
-
-const normalizeScopeArgs = (
-  ownerOrOptions?: unknown,
-  repoOrOptions?: unknown,
-  maybeOptions?: unknown,
-): ScopeArgs => {
-  const options: Record<string, unknown> = {}
-  let owner: string | undefined
-  let repo: string | undefined
-
-  const absorb = (value: unknown): string | undefined => {
-    if (value === undefined || value === null) {
-      return undefined
-    }
-
-    if (isRecord(value)) {
-      Object.assign(options, value)
-      return undefined
-    }
-
-    const asText = String(value).trim()
-    return asText.length > 0 ? asText : undefined
-  }
-
-  owner = absorb(ownerOrOptions)
-  repo = absorb(repoOrOptions)
-
-  if (isRecord(maybeOptions)) {
-    Object.assign(options, maybeOptions)
-  }
-
-  return {
-    ...(owner ? { owner } : {}),
-    ...(repo ? { repo } : {}),
-    options,
-  }
-}
-
-const normalizeNamedScopeArgs = (
-  labelName: unknown,
-  ownerOrOptions?: unknown,
-  repoOrOptions?: unknown,
-  maybeOptions?: unknown,
-): NamedScopeArgs => {
-  const name = toTrimmedString(labelName)
-  if (!name) {
-    throw new Error('Label name is required.')
-  }
-
-  return {
-    name,
-    ...normalizeScopeArgs(ownerOrOptions, repoOrOptions, maybeOptions),
-  }
-}
-
-export interface GitLabelManagementDefaults {
-  defaultOwner?: string
-  defaultRepo?: string
-}
-
-const resolveOwnerRepo = (
-  scope: Pick<ScopeArgs, 'owner' | 'repo'>,
-  defaults: GitLabelManagementDefaults,
-): { owner: string; repo: string } => {
-  const owner = scope.owner ?? defaults.defaultOwner
-  const repo = scope.repo ?? defaults.defaultRepo
-
-  if (!owner || !repo) {
-    throw new Error(
-      'Owner/repo is required. Pass owner and repo args or set defaultOwner/defaultRepo when creating the API.',
-    )
-  }
-
-  return { owner, repo }
-}
-
-const resolveLabelNamespace = (api: GitServiceApi): GitServiceApi => {
-  const direct = (api as Record<string, unknown>).label
-  if (isRecord(direct)) {
-    return direct as GitServiceApi
-  }
-
-  const repoNamespace = (api as Record<string, unknown>).repo
-  if (isRecord(repoNamespace)) {
-    const repoLabel = (repoNamespace as Record<string, unknown>).label
-    if (isRecord(repoLabel)) {
-      return repoLabel as GitServiceApi
-    }
-  }
-
-  throw new Error('Git service API does not expose label namespace')
-}
-
-type LabelCrudFeature = 'list' | 'create' | 'edit' | 'delete'
-
-const resolveLabelMethod = (api: GitServiceApi, feature: LabelCrudFeature): GitServiceApiMethod => {
-  const labelNamespace = resolveLabelNamespace(api)
-  const method = (labelNamespace as Record<string, unknown>)[feature]
-  if (typeof method !== 'function') {
-    throw new Error(`Git service API does not expose label.${feature}`)
-  }
-  return method as GitServiceApiMethod
-}
-
-const executeLabelCall = async (
-  method: GitServiceApiMethod,
-  owner: string,
-  repo: string,
-  pathArgs: unknown[] = [],
-  options: Record<string, unknown> = {},
-): Promise<GitServiceApiExecutionResult<unknown>> => {
-  const invocationArgs: unknown[] = [owner, repo, ...pathArgs]
-  if (Object.keys(options).length > 0) {
-    invocationArgs.push(options)
-  }
-  return method(...invocationArgs) as Promise<GitServiceApiExecutionResult<unknown>>
-}
-
-const ensureOk = (result: GitServiceApiExecutionResult<unknown>, context: string): void => {
-  if (!result.ok) {
-    throw new Error(`${context}: status=${result.status} url=${result.request.url}`)
-  }
-}
-
-export interface GitRepositoryLabel {
-  id: number | null
-  name: string
-  color: string | null
-  description: string | null
-  exclusive: boolean | null
-  url: string | null
-  raw: Record<string, unknown>
-}
-
-const normalizeRepositoryLabel = (raw: unknown): GitRepositoryLabel | null => {
-  if (!isRecord(raw)) {
-    return null
-  }
-
-  const name = toTrimmedString(raw.name)
-  if (!name) {
-    return null
-  }
-
-  const id = toPositiveInteger(raw.id ?? raw.number ?? raw.ID)
-  const color = toTrimmedString(raw.color)
-  const description = toTrimmedString(raw.description)
-  const url = toTrimmedString(raw.url ?? raw.html_url)
-  const exclusive = typeof raw.exclusive === 'boolean'
-    ? raw.exclusive
-    : typeof raw.is_exclusive === 'boolean'
-      ? raw.is_exclusive
-      : null
-
-  return {
-    id,
-    name,
-    color,
-    description,
-    exclusive,
-    url,
-    raw: { ...raw },
-  }
-}
-
-const dedupeRepositoryLabels = (labels: GitRepositoryLabel[]): GitRepositoryLabel[] => {
-  const seen = new Set<string>()
-  const unique: GitRepositoryLabel[] = []
-
-  for (const label of labels) {
-    const key = label.id !== null ? `id:${label.id}` : `name:${label.name.toLowerCase()}`
-    if (seen.has(key)) {
-      continue
-    }
-    seen.add(key)
-    unique.push(label)
-  }
-
-  return unique
-}
-
-export const extractRepositoryLabels = (raw: unknown): GitRepositoryLabel[] => {
-  if (Array.isArray(raw)) {
-    const labels = raw
-      .map((entry) => normalizeRepositoryLabel(entry))
-      .filter((entry): entry is GitRepositoryLabel => entry !== null)
-    return dedupeRepositoryLabels(labels)
-  }
-
-  if (isRecord(raw)) {
-    if (Array.isArray(raw.labels)) {
-      return extractRepositoryLabels(raw.labels)
-    }
-
-    if (Array.isArray(raw.data)) {
-      return extractRepositoryLabels(raw.data)
-    }
-  }
-
-  return []
-}
-
-const withBody = <T>(
-  result: GitServiceApiExecutionResult<unknown>,
-  body: T,
-): GitServiceApiExecutionResult<T> => ({
-  ...result,
-  body,
-})
-
-type LabelListContext = {
-  labels: GitRepositoryLabel[]
-  context: GitServiceApiExecutionResult<unknown>
-}
-
-const listRepositoryLabels = async (
-  api: GitServiceApi,
-  owner: string,
-  repo: string,
-  options: {
-    query?: Record<string, string | number | boolean>
-    allPages?: boolean
-  } = {},
-): Promise<LabelListContext> => {
-  const listMethod = resolveLabelMethod(api, 'list')
-  const labels: GitRepositoryLabel[] = []
-  const query = options.query ?? {}
-  const allPages = options.allPages ?? true
-  const paginate = allPages && query.page === undefined && query.limit === undefined
-  let page = 1
-  let context: GitServiceApiExecutionResult<unknown> | null = null
-
-  while (page <= MAX_LABEL_LIST_PAGES) {
-    const queryForCall: Record<string, string | number | boolean> = { ...query }
-    if (paginate) {
-      queryForCall.limit = LABEL_LIST_PAGE_SIZE
-      queryForCall.page = page
-    }
-
-    const requestOptions = Object.keys(queryForCall).length > 0
-      ? { query: queryForCall }
-      : {}
-
-    const result = await executeLabelCall(listMethod, owner, repo, [], requestOptions)
-    ensureOk(result, `Failed to list labels for ${owner}/${repo}`)
-    context = result
-
-    const batch = extractRepositoryLabels(result.body)
-    labels.push(...batch)
-
-    if (!paginate || batch.length < LABEL_LIST_PAGE_SIZE) {
-      break
-    }
-
-    page += 1
-  }
-
-  if (paginate && page > MAX_LABEL_LIST_PAGES) {
-    throw new Error(`Label pagination exceeded ${MAX_LABEL_LIST_PAGES} pages for ${owner}/${repo}.`)
-  }
-
-  if (!context) {
-    throw new Error(`Label listing did not execute for ${owner}/${repo}.`)
-  }
-
-  return {
-    labels: dedupeRepositoryLabels(labels),
-    context,
-  }
-}
-
-type LabelLookupContext = LabelListContext & {
-  match: GitRepositoryLabel | null
-}
-
-const findRepositoryLabelByName = async (
-  api: GitServiceApi,
-  owner: string,
-  repo: string,
-  name: string,
-  options: {
-    caseSensitive?: boolean
-  } = {},
-): Promise<LabelLookupContext> => {
-  const listed = await listRepositoryLabels(api, owner, repo, { allPages: true })
-  const caseSensitive = options.caseSensitive ?? false
-  const target = caseSensitive ? name : name.toLowerCase()
-
-  const match = listed.labels.find((label) => {
-    const candidate = caseSensitive ? label.name : label.name.toLowerCase()
-    return candidate === target
-  }) ?? null
-
-  return {
-    ...listed,
-    match,
-  }
-}
-
-const buildLabelUpsertPayload = (
-  name: string,
-  options: Record<string, unknown>,
-  mode: 'create' | 'update',
-): Record<string, unknown> => {
-  const payload: Record<string, unknown> = {}
-
-  const data = options.data
-  if (isRecord(data)) {
-    Object.assign(payload, data)
-  }
-
-  if (options.color !== undefined) payload.color = options.color
-  if (options.description !== undefined) payload.description = options.description
-  if (options.exclusive !== undefined) payload.exclusive = options.exclusive
-  if (options.isArchived !== undefined) payload.is_archived = options.isArchived
-  if (options.is_archived !== undefined) payload.is_archived = options.is_archived
-
-  if (mode === 'create') {
-    payload.name = name
-    const color = toTrimmedString(payload.color)
-    if (!color) {
-      throw new Error(`Label "${name}" requires a non-empty "color" when creating.`)
-    }
-    payload.color = color
-  } else {
-    delete payload.name
-  }
-
-  return payload
-}
-
-type GitLabelListManagedBody = {
-  total: number
-  labels: GitRepositoryLabel[]
-}
-
-type GitLabelGetByNameBody = {
-  found: boolean
-  label: GitRepositoryLabel | null
-}
-
-type GitLabelUpsertBody = {
-  action: 'created' | 'updated' | 'unchanged'
-  label: GitRepositoryLabel
-}
-
-type GitLabelDeleteByNameBody = {
-  deleted: boolean
-  label: GitRepositoryLabel | null
-}
-
-export type GitLabelManagementApi = {
-  listManaged: GitServiceApiMethod
-  getByName: GitServiceApiMethod
-  upsert: GitServiceApiMethod
-  deleteByName: GitServiceApiMethod
-}
-
-export const createGitLabelManagementApi = (
-  api: GitServiceApi,
-  defaults: GitLabelManagementDefaults = {},
-): GitLabelManagementApi => {
-  return {
-    listManaged: async (
-      ownerOrOptions?: unknown,
-      repoOrOptions?: unknown,
-      maybeOptions?: unknown,
-    ): Promise<GitServiceApiExecutionResult<GitLabelListManagedBody>> => {
-      const scope = normalizeScopeArgs(ownerOrOptions, repoOrOptions, maybeOptions)
-      const { owner, repo } = resolveOwnerRepo(scope, defaults)
-      const allPages = toBoolean(scope.options.allPages, true)
-      const query = toQueryRecord(scope.options.query)
-
-      const listed = await listRepositoryLabels(api, owner, repo, { allPages, query })
-      return withBody(listed.context, {
-        total: listed.labels.length,
-        labels: listed.labels,
-      })
-    },
-
-    getByName: async (
-      labelName: unknown,
-      ownerOrOptions?: unknown,
-      repoOrOptions?: unknown,
-      maybeOptions?: unknown,
-    ): Promise<GitServiceApiExecutionResult<GitLabelGetByNameBody>> => {
-      const parsed = normalizeNamedScopeArgs(labelName, ownerOrOptions, repoOrOptions, maybeOptions)
-      const { owner, repo } = resolveOwnerRepo(parsed, defaults)
-      const caseSensitive = toBoolean(parsed.options.caseSensitive, false)
-
-      const lookup = await findRepositoryLabelByName(api, owner, repo, parsed.name, { caseSensitive })
-      return withBody(lookup.context, {
-        found: lookup.match !== null,
-        label: lookup.match,
-      })
-    },
-
-    upsert: async (
-      labelName: unknown,
-      ownerOrOptions?: unknown,
-      repoOrOptions?: unknown,
-      maybeOptions?: unknown,
-    ): Promise<GitServiceApiExecutionResult<GitLabelUpsertBody>> => {
-      const parsed = normalizeNamedScopeArgs(labelName, ownerOrOptions, repoOrOptions, maybeOptions)
-      const { owner, repo } = resolveOwnerRepo(parsed, defaults)
-      const caseSensitive = toBoolean(parsed.options.caseSensitive, false)
-
-      const lookup = await findRepositoryLabelByName(api, owner, repo, parsed.name, { caseSensitive })
-      if (lookup.match) {
-        const payload = buildLabelUpsertPayload(parsed.name, parsed.options, 'update')
-        if (Object.keys(payload).length === 0) {
-          return withBody(lookup.context, {
-            action: 'unchanged',
-            label: lookup.match,
-          })
-        }
-
-        if (lookup.match.id === null) {
-          throw new Error(`Label "${parsed.name}" does not expose an id and cannot be updated.`)
-        }
-
-        const editMethod = resolveLabelMethod(api, 'edit')
-        const result = await executeLabelCall(editMethod, owner, repo, [lookup.match.id], { data: payload })
-        ensureOk(result, `Failed to update label "${parsed.name}" in ${owner}/${repo}`)
-
-        const updated = normalizeRepositoryLabel(result.body)
-        if (!updated) {
-          throw new Error(`Update label response invalid for "${parsed.name}" in ${owner}/${repo}.`)
-        }
-
-        return withBody(result, {
-          action: 'updated',
-          label: updated,
-        })
-      }
-
-      const payload = buildLabelUpsertPayload(parsed.name, parsed.options, 'create')
-      const createMethod = resolveLabelMethod(api, 'create')
-      const result = await executeLabelCall(createMethod, owner, repo, [], { data: payload })
-      ensureOk(result, `Failed to create label "${parsed.name}" in ${owner}/${repo}`)
-
-      const created = normalizeRepositoryLabel(result.body)
-      if (!created) {
-        throw new Error(`Create label response invalid for "${parsed.name}" in ${owner}/${repo}.`)
-      }
-
-      return withBody(result, {
-        action: 'created',
-        label: created,
-      })
-    },
-
-    deleteByName: async (
-      labelName: unknown,
-      ownerOrOptions?: unknown,
-      repoOrOptions?: unknown,
-      maybeOptions?: unknown,
-    ): Promise<GitServiceApiExecutionResult<GitLabelDeleteByNameBody>> => {
-      const parsed = normalizeNamedScopeArgs(labelName, ownerOrOptions, repoOrOptions, maybeOptions)
-      const { owner, repo } = resolveOwnerRepo(parsed, defaults)
-      const strict = toBoolean(parsed.options.strict, false)
-      const caseSensitive = toBoolean(parsed.options.caseSensitive, false)
-
-      const lookup = await findRepositoryLabelByName(api, owner, repo, parsed.name, { caseSensitive })
-      if (!lookup.match) {
-        if (strict) {
-          throw new Error(`Label "${parsed.name}" was not found in ${owner}/${repo}.`)
-        }
-
-        return withBody(lookup.context, {
-          deleted: false,
-          label: null,
-        })
-      }
-
-      if (lookup.match.id === null) {
-        throw new Error(`Label "${parsed.name}" does not expose an id and cannot be deleted.`)
-      }
-
-      const deleteMethod = resolveLabelMethod(api, 'delete')
-      const result = await executeLabelCall(deleteMethod, owner, repo, [lookup.match.id])
-      ensureOk(result, `Failed to delete label "${parsed.name}" in ${owner}/${repo}`)
-
-      return withBody(result, {
-        deleted: true,
-        label: lookup.match,
-      })
-    },
-  }
-}
-
-const ensureNamespace = (root: GitServiceApi, path: string[]): GitServiceApi => {
-  let cursor: GitServiceApi = root
-  for (const segment of path) {
-    const current = cursor[segment]
-    if (!isRecord(current)) {
-      cursor[segment] = {}
-    }
-    cursor = cursor[segment] as GitServiceApi
-  }
-  return cursor
-}
-
-export const attachGitLabelManagementApi = (
-  api: GitServiceApi,
-  defaults: GitLabelManagementDefaults = {},
-): void => {
-  const methods = createGitLabelManagementApi(api, defaults)
-  const targets = [
-    ensureNamespace(api, ['label']),
-    ensureNamespace(api, ['repo', 'label']),
-  ]
-
-  for (const target of targets) {
-    for (const [name, method] of Object.entries(methods)) {
-      if (!(name in target)) {
-        target[name] = method
-      }
-    }
-  }
-}
-
+import type { GitServiceApi, GitServiceApiExecutionResult, GitServiceApiMethod } from './git-service-api'
+
+const LABEL_LIST_PAGE_SIZE = 100
+const MAX_LABEL_LIST_PAGES = 100
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+const toTrimmedString = (value: unknown): string | null => {
+  if (typeof value !== 'string') {
+    return null
+  }
+  const trimmed = value.trim()
+  return trimmed.length > 0 ? trimmed : null
+}
+
+const toPositiveInteger = (value: unknown): number | null => {
+  const candidate = Number(value)
+  if (!Number.isFinite(candidate) || candidate <= 0 || Math.floor(candidate) !== candidate) {
+    return null
+  }
+  return candidate
+}
+
+const toBoolean = (value: unknown, fallback: boolean): boolean => {
+  if (typeof value === 'boolean') {
+    return value
+  }
+
+  if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase()
+    if (normalized === 'true' || normalized === '1' || normalized === 'yes') {
+      return true
+    }
+    if (normalized === 'false' || normalized === '0' || normalized === 'no') {
+      return false
+    }
+  }
+
+  return fallback
+}
+
+const toQueryRecord = (raw: unknown): Record<string, string | number | boolean> => {
+  if (!isRecord(raw)) {
+    return {}
+  }
+
+  const query: Record<string, string | number | boolean> = {}
+  for (const [key, value] of Object.entries(raw)) {
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+      query[key] = value
+    }
+  }
+  return query
+}
+
+type ScopeArgs = {
+  owner?: string
+  repo?: string
+  options: Record<string, unknown>
+}
+
+type NamedScopeArgs = ScopeArgs & {
+  name: string
+}
+
+const normalizeScopeArgs = (
+  ownerOrOptions?: unknown,
+  repoOrOptions?: unknown,
+  maybeOptions?: unknown,
+): ScopeArgs => {
+  const options: Record<string, unknown> = {}
+  let owner: string | undefined
+  let repo: string | undefined
+
+  const absorb = (value: unknown): string | undefined => {
+    if (value === undefined || value === null) {
+      return undefined
+    }
+
+    if (isRecord(value)) {
+      Object.assign(options, value)
+      return undefined
+    }
+
+    const asText = String(value).trim()
+    return asText.length > 0 ? asText : undefined
+  }
+
+  owner = absorb(ownerOrOptions)
+  repo = absorb(repoOrOptions)
+
+  if (isRecord(maybeOptions)) {
+    Object.assign(options, maybeOptions)
+  }
+
+  return {
+    ...(owner ? { owner } : {}),
+    ...(repo ? { repo } : {}),
+    options,
+  }
+}
+
+const normalizeNamedScopeArgs = (
+  labelName: unknown,
+  ownerOrOptions?: unknown,
+  repoOrOptions?: unknown,
+  maybeOptions?: unknown,
+): NamedScopeArgs => {
+  const name = toTrimmedString(labelName)
+  if (!name) {
+    throw new Error('Label name is required.')
+  }
+
+  return {
+    name,
+    ...normalizeScopeArgs(ownerOrOptions, repoOrOptions, maybeOptions),
+  }
+}
+
+export interface GitLabelManagementDefaults {
+  defaultOwner?: string
+  defaultRepo?: string
+}
+
+const resolveOwnerRepo = (
+  scope: Pick<ScopeArgs, 'owner' | 'repo'>,
+  defaults: GitLabelManagementDefaults,
+): { owner: string; repo: string } => {
+  const owner = scope.owner ?? defaults.defaultOwner
+  const repo = scope.repo ?? defaults.defaultRepo
+
+  if (!owner || !repo) {
+    throw new Error(
+      'Owner/repo is required. Pass owner and repo args or set defaultOwner/defaultRepo when creating the API.',
+    )
+  }
+
+  return { owner, repo }
+}
+
+const resolveLabelNamespace = (api: GitServiceApi): GitServiceApi => {
+  const direct = (api as Record<string, unknown>).label
+  if (isRecord(direct)) {
+    return direct as GitServiceApi
+  }
+
+  const repoNamespace = (api as Record<string, unknown>).repo
+  if (isRecord(repoNamespace)) {
+    const repoLabel = (repoNamespace as Record<string, unknown>).label
+    if (isRecord(repoLabel)) {
+      return repoLabel as GitServiceApi
+    }
+  }
+
+  throw new Error('Git service API does not expose label namespace')
+}
+
+type LabelCrudFeature = 'list' | 'create' | 'edit' | 'delete'
+
+const resolveLabelMethod = (api: GitServiceApi, feature: LabelCrudFeature): GitServiceApiMethod => {
+  const labelNamespace = resolveLabelNamespace(api)
+  const method = (labelNamespace as Record<string, unknown>)[feature]
+  if (typeof method !== 'function') {
+    throw new Error(`Git service API does not expose label.${feature}`)
+  }
+  return method as GitServiceApiMethod
+}
+
+const executeLabelCall = async (
+  method: GitServiceApiMethod,
+  owner: string,
+  repo: string,
+  pathArgs: unknown[] = [],
+  options: Record<string, unknown> = {},
+): Promise<GitServiceApiExecutionResult<unknown>> => {
+  const invocationArgs: unknown[] = [owner, repo, ...pathArgs]
+  if (Object.keys(options).length > 0) {
+    invocationArgs.push(options)
+  }
+  return method(...invocationArgs) as Promise<GitServiceApiExecutionResult<unknown>>
+}
+
+const ensureOk = (result: GitServiceApiExecutionResult<unknown>, context: string): void => {
+  if (!result.ok) {
+    throw new Error(`${context}: status=${result.status} url=${result.request.url}`)
+  }
+}
+
+export interface GitRepositoryLabel {
+  id: number | null
+  name: string
+  color: string | null
+  description: string | null
+  exclusive: boolean | null
+  url: string | null
+  raw: Record<string, unknown>
+}
+
+const normalizeRepositoryLabel = (raw: unknown): GitRepositoryLabel | null => {
+  if (!isRecord(raw)) {
+    return null
+  }
+
+  const name = toTrimmedString(raw.name)
+  if (!name) {
+    return null
+  }
+
+  const id = toPositiveInteger(raw.id ?? raw.number ?? raw.ID)
+  const color = toTrimmedString(raw.color)
+  const description = toTrimmedString(raw.description)
+  const url = toTrimmedString(raw.url ?? raw.html_url)
+  const exclusive = typeof raw.exclusive === 'boolean'
+    ? raw.exclusive
+    : typeof raw.is_exclusive === 'boolean'
+      ? raw.is_exclusive
+      : null
+
+  return {
+    id,
+    name,
+    color,
+    description,
+    exclusive,
+    url,
+    raw: { ...raw },
+  }
+}
+
+const dedupeRepositoryLabels = (labels: GitRepositoryLabel[]): GitRepositoryLabel[] => {
+  const seen = new Set<string>()
+  const unique: GitRepositoryLabel[] = []
+
+  for (const label of labels) {
+    const key = label.id !== null ? `id:${label.id}` : `name:${label.name.toLowerCase()}`
+    if (seen.has(key)) {
+      continue
+    }
+    seen.add(key)
+    unique.push(label)
+  }
+
+  return unique
+}
+
+export const extractRepositoryLabels = (raw: unknown): GitRepositoryLabel[] => {
+  if (Array.isArray(raw)) {
+    const labels = raw
+      .map((entry) => normalizeRepositoryLabel(entry))
+      .filter((entry): entry is GitRepositoryLabel => entry !== null)
+    return dedupeRepositoryLabels(labels)
+  }
+
+  if (isRecord(raw)) {
+    if (Array.isArray(raw.labels)) {
+      return extractRepositoryLabels(raw.labels)
+    }
+
+    if (Array.isArray(raw.data)) {
+      return extractRepositoryLabels(raw.data)
+    }
+  }
+
+  return []
+}
+
+const withBody = <T>(
+  result: GitServiceApiExecutionResult<unknown>,
+  body: T,
+): GitServiceApiExecutionResult<T> => ({
+  ...result,
+  body,
+})
+
+type LabelListContext = {
+  labels: GitRepositoryLabel[]
+  context: GitServiceApiExecutionResult<unknown>
+}
+
+const listRepositoryLabels = async (
+  api: GitServiceApi,
+  owner: string,
+  repo: string,
+  options: {
+    query?: Record<string, string | number | boolean>
+    allPages?: boolean
+  } = {},
+): Promise<LabelListContext> => {
+  const listMethod = resolveLabelMethod(api, 'list')
+  const labels: GitRepositoryLabel[] = []
+  const query = options.query ?? {}
+  const allPages = options.allPages ?? true
+  const paginate = allPages && query.page === undefined && query.limit === undefined
+  let page = 1
+  let context: GitServiceApiExecutionResult<unknown> | null = null
+
+  while (page <= MAX_LABEL_LIST_PAGES) {
+    const queryForCall: Record<string, string | number | boolean> = { ...query }
+    if (paginate) {
+      queryForCall.limit = LABEL_LIST_PAGE_SIZE
+      queryForCall.page = page
+    }
+
+    const requestOptions = Object.keys(queryForCall).length > 0
+      ? { query: queryForCall }
+      : {}
+
+    const result = await executeLabelCall(listMethod, owner, repo, [], requestOptions)
+    ensureOk(result, `Failed to list labels for ${owner}/${repo}`)
+    context = result
+
+    const batch = extractRepositoryLabels(result.body)
+    labels.push(...batch)
+
+    if (!paginate || batch.length < LABEL_LIST_PAGE_SIZE) {
+      break
+    }
+
+    page += 1
+  }
+
+  if (paginate && page > MAX_LABEL_LIST_PAGES) {
+    throw new Error(`Label pagination exceeded ${MAX_LABEL_LIST_PAGES} pages for ${owner}/${repo}.`)
+  }
+
+  if (!context) {
+    throw new Error(`Label listing did not execute for ${owner}/${repo}.`)
+  }
+
+  return {
+    labels: dedupeRepositoryLabels(labels),
+    context,
+  }
+}
+
+type LabelLookupContext = LabelListContext & {
+  match: GitRepositoryLabel | null
+}
+
+const findRepositoryLabelByName = async (
+  api: GitServiceApi,
+  owner: string,
+  repo: string,
+  name: string,
+  options: {
+    caseSensitive?: boolean
+  } = {},
+): Promise<LabelLookupContext> => {
+  const listed = await listRepositoryLabels(api, owner, repo, { allPages: true })
+  const caseSensitive = options.caseSensitive ?? false
+  const target = caseSensitive ? name : name.toLowerCase()
+
+  const match = listed.labels.find((label) => {
+    const candidate = caseSensitive ? label.name : label.name.toLowerCase()
+    return candidate === target
+  }) ?? null
+
+  return {
+    ...listed,
+    match,
+  }
+}
+
+const buildLabelUpsertPayload = (
+  name: string,
+  options: Record<string, unknown>,
+  mode: 'create' | 'update',
+): Record<string, unknown> => {
+  const payload: Record<string, unknown> = {}
+
+  const data = options.data
+  if (isRecord(data)) {
+    Object.assign(payload, data)
+  }
+
+  if (options.color !== undefined) payload.color = options.color
+  if (options.description !== undefined) payload.description = options.description
+  if (options.exclusive !== undefined) payload.exclusive = options.exclusive
+  if (options.isArchived !== undefined) payload.is_archived = options.isArchived
+  if (options.is_archived !== undefined) payload.is_archived = options.is_archived
+
+  if (mode === 'create') {
+    payload.name = name
+    const color = toTrimmedString(payload.color)
+    if (!color) {
+      throw new Error(`Label "${name}" requires a non-empty "color" when creating.`)
+    }
+    payload.color = color
+  } else {
+    delete payload.name
+  }
+
+  return payload
+}
+
+type GitLabelListManagedBody = {
+  total: number
+  labels: GitRepositoryLabel[]
+}
+
+type GitLabelGetByNameBody = {
+  found: boolean
+  label: GitRepositoryLabel | null
+}
+
+type GitLabelUpsertBody = {
+  action: 'created' | 'updated' | 'unchanged'
+  label: GitRepositoryLabel
+}
+
+type GitLabelDeleteByNameBody = {
+  deleted: boolean
+  label: GitRepositoryLabel | null
+}
+
+export type GitLabelManagementApi = {
+  listManaged: GitServiceApiMethod
+  getByName: GitServiceApiMethod
+  upsert: GitServiceApiMethod
+  deleteByName: GitServiceApiMethod
+}
+
+export const createGitLabelManagementApi = (
+  api: GitServiceApi,
+  defaults: GitLabelManagementDefaults = {},
+): GitLabelManagementApi => {
+  return {
+    listManaged: async (
+      ownerOrOptions?: unknown,
+      repoOrOptions?: unknown,
+      maybeOptions?: unknown,
+    ): Promise<GitServiceApiExecutionResult<GitLabelListManagedBody>> => {
+      const scope = normalizeScopeArgs(ownerOrOptions, repoOrOptions, maybeOptions)
+      const { owner, repo } = resolveOwnerRepo(scope, defaults)
+      const allPages = toBoolean(scope.options.allPages, true)
+      const query = toQueryRecord(scope.options.query)
+
+      const listed = await listRepositoryLabels(api, owner, repo, { allPages, query })
+      return withBody(listed.context, {
+        total: listed.labels.length,
+        labels: listed.labels,
+      })
+    },
+
+    getByName: async (
+      labelName: unknown,
+      ownerOrOptions?: unknown,
+      repoOrOptions?: unknown,
+      maybeOptions?: unknown,
+    ): Promise<GitServiceApiExecutionResult<GitLabelGetByNameBody>> => {
+      const parsed = normalizeNamedScopeArgs(labelName, ownerOrOptions, repoOrOptions, maybeOptions)
+      const { owner, repo } = resolveOwnerRepo(parsed, defaults)
+      const caseSensitive = toBoolean(parsed.options.caseSensitive, false)
+
+      const lookup = await findRepositoryLabelByName(api, owner, repo, parsed.name, { caseSensitive })
+      return withBody(lookup.context, {
+        found: lookup.match !== null,
+        label: lookup.match,
+      })
+    },
+
+    upsert: async (
+      labelName: unknown,
+      ownerOrOptions?: unknown,
+      repoOrOptions?: unknown,
+      maybeOptions?: unknown,
+    ): Promise<GitServiceApiExecutionResult<GitLabelUpsertBody>> => {
+      const parsed = normalizeNamedScopeArgs(labelName, ownerOrOptions, repoOrOptions, maybeOptions)
+      const { owner, repo } = resolveOwnerRepo(parsed, defaults)
+      const caseSensitive = toBoolean(parsed.options.caseSensitive, false)
+
+      const lookup = await findRepositoryLabelByName(api, owner, repo, parsed.name, { caseSensitive })
+      if (lookup.match) {
+        const payload = buildLabelUpsertPayload(parsed.name, parsed.options, 'update')
+        if (Object.keys(payload).length === 0) {
+          return withBody(lookup.context, {
+            action: 'unchanged',
+            label: lookup.match,
+          })
+        }
+
+        if (lookup.match.id === null) {
+          throw new Error(`Label "${parsed.name}" does not expose an id and cannot be updated.`)
+        }
+
+        const editMethod = resolveLabelMethod(api, 'edit')
+        const result = await executeLabelCall(editMethod, owner, repo, [lookup.match.id], { data: payload })
+        ensureOk(result, `Failed to update label "${parsed.name}" in ${owner}/${repo}`)
+
+        const updated = normalizeRepositoryLabel(result.body)
+        if (!updated) {
+          throw new Error(`Update label response invalid for "${parsed.name}" in ${owner}/${repo}.`)
+        }
+
+        return withBody(result, {
+          action: 'updated',
+          label: updated,
+        })
+      }
+
+      const payload = buildLabelUpsertPayload(parsed.name, parsed.options, 'create')
+      const createMethod = resolveLabelMethod(api, 'create')
+      const result = await executeLabelCall(createMethod, owner, repo, [], { data: payload })
+      ensureOk(result, `Failed to create label "${parsed.name}" in ${owner}/${repo}`)
+
+      const created = normalizeRepositoryLabel(result.body)
+      if (!created) {
+        throw new Error(`Create label response invalid for "${parsed.name}" in ${owner}/${repo}.`)
+      }
+
+      return withBody(result, {
+        action: 'created',
+        label: created,
+      })
+    },
+
+    deleteByName: async (
+      labelName: unknown,
+      ownerOrOptions?: unknown,
+      repoOrOptions?: unknown,
+      maybeOptions?: unknown,
+    ): Promise<GitServiceApiExecutionResult<GitLabelDeleteByNameBody>> => {
+      const parsed = normalizeNamedScopeArgs(labelName, ownerOrOptions, repoOrOptions, maybeOptions)
+      const { owner, repo } = resolveOwnerRepo(parsed, defaults)
+      const strict = toBoolean(parsed.options.strict, false)
+      const caseSensitive = toBoolean(parsed.options.caseSensitive, false)
+
+      const lookup = await findRepositoryLabelByName(api, owner, repo, parsed.name, { caseSensitive })
+      if (!lookup.match) {
+        if (strict) {
+          throw new Error(`Label "${parsed.name}" was not found in ${owner}/${repo}.`)
+        }
+
+        return withBody(lookup.context, {
+          deleted: false,
+          label: null,
+        })
+      }
+
+      if (lookup.match.id === null) {
+        throw new Error(`Label "${parsed.name}" does not expose an id and cannot be deleted.`)
+      }
+
+      const deleteMethod = resolveLabelMethod(api, 'delete')
+      const result = await executeLabelCall(deleteMethod, owner, repo, [lookup.match.id])
+      ensureOk(result, `Failed to delete label "${parsed.name}" in ${owner}/${repo}`)
+
+      return withBody(result, {
+        deleted: true,
+        label: lookup.match,
+      })
+    },
+  }
+}
+
+const ensureNamespace = (root: GitServiceApi, path: string[]): GitServiceApi => {
+  let cursor: GitServiceApi = root
+  for (const segment of path) {
+    const current = cursor[segment]
+    if (!isRecord(current)) {
+      cursor[segment] = {}
+    }
+    cursor = cursor[segment] as GitServiceApi
+  }
+  return cursor
+}
+
+export const attachGitLabelManagementApi = (
+  api: GitServiceApi,
+  defaults: GitLabelManagementDefaults = {},
+): void => {
+  const methods = createGitLabelManagementApi(api, defaults)
+  const targets = [
+    ensureNamespace(api, ['label']),
+    ensureNamespace(api, ['repo', 'label']),
+  ]
+
+  for (const target of targets) {
+    for (const [name, method] of Object.entries(methods)) {
+      if (!(name in target)) {
+        target[name] = method
+      }
+    }
+  }
+}
+