@mohou/mcp-client 1.0.20

package/README.md

@@ -0,0 +1,8 @@
+---
+status: locked
+updated: 2026-10-01
+---
+
+# @mohou/mcp-client
+
+Role: `provider`. External MCP sessions for `ctx.mcp`. Not the runtime provider. Product: [ctx.mcp](../../../docs/product/mcp-client/ctx-mcp.md).

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@mohou/mcp-client",
+  "version": "1.0.20",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "lib/types",
+    "README.md",
+    "!**/*.tsbuildinfo"
+  ],
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,305 @@
+import { isDeepStrictEqual } from 'node:util'
+
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js'
+
+import { McpError } from './codes.ts'
+import type { McpServerSpec } from './config.ts'
+import { mayHoldCredential } from './secrets.ts'
+
+/** Reconnects after a live session drops. Not a locked number. */
+const DEFAULT_RECONNECT_BUDGET = 2
+
+interface ToolResult {
+  content?: Array<{ type: string; text?: string }>
+  structuredContent?: unknown
+  isError?: boolean
+}
+
+interface Session {
+  client: Client
+  generation: number
+}
+
+/**
+ * External MCP sessions. The first call opens a server. One session per id.
+ * A dropped live session reconnects until the budget is spent, then that call fails.
+ * The next call may open the server again.
+ * The set can be replaced while running: {@link setServers} closes the sessions it retires.
+ * This client does not register tools on a model. It does not unwrap `{ input: string }`.
+ */
+export class McpClient {
+  private readonly servers = new Map<string, McpServerSpec>()
+  private readonly sessions = new Map<string, Session>()
+  private readonly opening = new Map<string, Promise<Session>>()
+  private readonly generation = new Map<string, number>()
+  private readonly reconnects = new Map<string, number>()
+  private readonly dropped = new Set<string>()
+  private readonly recovering = new Set<string>()
+  private readonly parentEnv: NodeJS.ProcessEnv
+  private readonly reconnectBudget: number
+
+  /**
+   * @param servers - resolved specs. This client copies the map so exhaustion can drop one id.
+   * @param parentEnv - ambient environment; credential-shaped names are not forwarded
+   * @param reconnectBudget - how many times a live session may be replaced. Not locked.
+   */
+  constructor(
+    servers: Record<string, McpServerSpec>,
+    parentEnv: NodeJS.ProcessEnv = process.env,
+    reconnectBudget = DEFAULT_RECONNECT_BUDGET,
+  ) {
+    this.parentEnv = parentEnv
+    this.reconnectBudget = reconnectBudget
+    for (const [id, spec] of Object.entries(servers)) this.servers.set(id, spec)
+  }
+
+  /**
+   * Call one tool. Args are the tool's own object.
+   * @param serverId - key in the resolved config
+   * @param toolName - the server's tool name
+   * @param args - tool arguments; omitted means an empty object
+   */
+  async call(serverId: string, toolName: string, args?: Record<string, unknown>): Promise<unknown> {
+    this.beginAttempt(serverId)
+    const result = await this.withSession(serverId, client => (
+      client.callTool({ name: toolName, arguments: args ?? {} }) as Promise<ToolResult>
+    ))
+    if (result.isError === true) {
+      const spec = this.servers.get(serverId)
+      const text = textOf(result)
+      throw new McpError('mcp-tool-failed', this.redact(text || 'mcp tool failed', spec), { cause: result })
+    }
+    if (result.structuredContent !== undefined) return result.structuredContent
+    if (result.content !== undefined && result.content.every(block => block.type === 'text')) return textOf(result)
+    return result.content ?? null
+  }
+
+  /** Server ids still registered. Does not open a connection. */
+  serverIds(): string[] {
+    return [...this.servers.keys()]
+  }
+
+  /**
+   * Replace the whole set. An id whose spec is deep-equal keeps its session and its budget.
+   * A removed id, or one whose spec changed, closes its session: the next call opens the new spec.
+   * The set is switched before any session closes, so a call that starts during this sees the new set.
+   * @param servers - resolved specs; the client copies the map
+   */
+  async setServers(servers: Record<string, McpServerSpec>): Promise<void> {
+    const retired = [...this.servers].filter(([id, spec]) => {
+      const next = servers[id]
+      return next === undefined || !isDeepStrictEqual(spec, next)
+    })
+    this.servers.clear()
+    for (const [id, spec] of Object.entries(servers)) this.servers.set(id, spec)
+    for (const [id] of retired) await this.closeServer(id)
+  }
+
+  /**
+   * List tools on one server. Opens the session if needed.
+   * @param serverId - key in the resolved config
+   */
+  async listTools(serverId: string): Promise<Array<{
+    name: string
+    description?: string
+    inputSchema: Record<string, unknown>
+    outputSchema?: Record<string, unknown>
+  }>> {
+    this.beginAttempt(serverId)
+    return this.withSession(serverId, async (client) => {
+      const tools: Array<{
+        name: string
+        description?: string
+        inputSchema: Record<string, unknown>
+        outputSchema?: Record<string, unknown>
+      }> = []
+      let cursor: string | undefined
+      do {
+        const page = await client.listTools(cursor === undefined ? undefined : { cursor }) as {
+          tools: Array<{
+            name: string
+            description?: string
+            inputSchema: Record<string, unknown>
+            outputSchema?: Record<string, unknown>
+          }>
+          nextCursor?: string
+        }
+        tools.push(...page.tools)
+        cursor = page.nextCursor
+      } while (cursor !== undefined)
+      return tools
+    })
+  }
+
+  /** Close every session and wait for stdio children to exit. */
+  async dispose(): Promise<void> {
+    const sessions = [...this.sessions.values()]
+    this.sessions.clear()
+    this.generation.clear()
+    await Promise.all(sessions.map(session => session.client.close().catch(() => undefined)))
+  }
+
+  private async withSession<T>(serverId: string, work: (client: Client) => Promise<T>): Promise<T> {
+    for (;;) {
+      const spec = this.servers.get(serverId)
+      if (spec === undefined) throw new McpError('mcp-not-connected', `mcp server is not connected: ${serverId}`)
+      if (this.dropped.has(serverId) && !this.allowReconnect(serverId)) {
+        throw new McpError('mcp-start-failed', `mcp server stopped: ${serverId}`)
+      }
+      const session = await this.session(serverId, spec)
+      try {
+        const value = await work(session.client)
+        this.reconnects.delete(serverId)
+        return value
+      } catch (error) {
+        this.recovering.add(serverId)
+        await this.closeGeneration(session)
+        this.recovering.delete(serverId)
+        this.dropped.delete(serverId)
+        if (isClosed(error) && this.spendReconnect(serverId)) continue
+        throw new McpError(
+          isClosed(error) ? 'mcp-start-failed' : 'mcp-tool-failed',
+          this.redact(error instanceof Error ? error.message : 'mcp tool failed', spec),
+          { cause: error },
+        )
+      }
+    }
+  }
+
+  private beginAttempt(serverId: string): void {
+    this.reconnects.delete(serverId)
+    this.dropped.delete(serverId)
+  }
+
+  private allowReconnect(serverId: string): boolean {
+    this.dropped.delete(serverId)
+    return this.spendReconnect(serverId)
+  }
+
+  private spendReconnect(serverId: string): boolean {
+    const used = (this.reconnects.get(serverId) ?? 0) + 1
+    this.reconnects.set(serverId, used)
+    return used <= this.reconnectBudget
+  }
+
+  private session(serverId: string, spec: McpServerSpec): Promise<Session> {
+    const live = this.sessions.get(serverId)
+    if (live !== undefined) return Promise.resolve(live)
+    const pending = this.opening.get(serverId)
+    if (pending !== undefined) return pending
+    const opening = this.open(serverId, spec).then((session) => {
+      this.opening.delete(serverId)
+      // The set may have been replaced or disposed while this was opening. Do not adopt it.
+      if (this.generation.get(serverId) !== session.generation) {
+        void session.client.close().catch(() => undefined)
+        throw new McpError('mcp-not-connected', `mcp server was replaced while opening: ${serverId}`)
+      }
+      this.sessions.set(serverId, session)
+      return session
+    }, (error: unknown) => {
+      this.opening.delete(serverId)
+      throw error
+    })
+    this.opening.set(serverId, opening)
+    return opening
+  }
+
+  private async open(serverId: string, spec: McpServerSpec): Promise<Session> {
+    const generation = (this.generation.get(serverId) ?? 0) + 1
+    this.generation.set(serverId, generation)
+    const client = new Client({ name: 'mini-app', version: '0.0.0' })
+    client.onclose = () => {
+      if (this.generation.get(serverId) !== generation) return
+      const current = this.sessions.get(serverId)
+      if (current?.generation === generation) this.sessions.delete(serverId)
+      if (!this.recovering.has(serverId)) this.dropped.add(serverId)
+    }
+    try {
+      await client.connect(transportFor(spec, scrubEnv(this.parentEnv)) as Transport)
+      return { client, generation }
+    } catch (error) {
+      await client.close().catch(() => undefined)
+      throw new McpError('mcp-start-failed', this.redact(error instanceof Error ? error.message : 'mcp server did not start', spec), { cause: error })
+    }
+  }
+
+  private async closeGeneration(session: Session): Promise<void> {
+    const current = [...this.sessions.entries()].find(([, live]) => live === session)
+    if (current !== undefined) this.sessions.delete(current[0])
+    await session.client.close().catch(() => undefined)
+  }
+
+  /**
+   * Retire one id: invalidate its generation, wait for an open in flight, close the live session,
+   * and forget its reconnect budget. The next call opens the spec this client holds now.
+   */
+  private async closeServer(serverId: string): Promise<void> {
+    this.generation.set(serverId, (this.generation.get(serverId) ?? 0) + 1)
+    const pending = this.opening.get(serverId)
+    if (pending !== undefined) await pending.catch(() => undefined)
+    const live = this.sessions.get(serverId)
+    if (live !== undefined) {
+      this.sessions.delete(serverId)
+      await live.client.close().catch(() => undefined)
+    }
+    this.reconnects.delete(serverId)
+    this.dropped.delete(serverId)
+    this.recovering.delete(serverId)
+  }
+
+  private redact(message: string, spec: McpServerSpec | undefined): string {
+    if (spec === undefined) return message
+    const secrets = specHasEnv(spec) ? Object.values(spec.env) : []
+    let text = message
+    for (const secret of secrets) {
+      if (secret.length < 4) continue
+      text = text.split(secret).join('[redacted]')
+    }
+    return text
+  }
+}
+
+function isClosed(error: unknown): boolean {
+  if (!(error instanceof Error)) return false
+  return error.message === 'Connection closed'
+    || error.message === 'Not connected'
+    || error.message.endsWith(': Connection closed')
+}
+
+function transportFor(spec: McpServerSpec, parent: Record<string, string>) {
+  if ('url' in spec) {
+    const url = new URL(spec.url)
+    if (spec.transport === 'sse') {
+      // Some servers still speak SSE. The contract keeps that transport.
+      // oxlint-disable-next-line typescript/no-deprecated
+      return new SSEClientTransport(url)
+    }
+    return new StreamableHTTPClientTransport(url, spec.headers === undefined ? undefined : { requestInit: { headers: spec.headers } })
+  }
+  return new StdioClientTransport({
+    command: spec.command,
+    args: spec.args ?? [],
+    env: { ...parent, ...spec.env },
+    stderr: 'pipe',
+  })
+}
+
+function scrubEnv(env: NodeJS.ProcessEnv): Record<string, string> {
+  const next: Record<string, string> = {}
+  for (const [key, value] of Object.entries(env)) {
+    if (value !== undefined && !mayHoldCredential(key)) next[key] = value
+  }
+  return next
+}
+
+function specHasEnv(spec: McpServerSpec): spec is McpServerSpec & { env: Record<string, string> } {
+  return 'command' in spec && spec.env !== undefined
+}
+
+function textOf(result: ToolResult): string {
+  return (result.content ?? []).flatMap(block => block.text === undefined ? [] : [block.text]).join('\n')
+}

package/src/codes.ts

@@ -0,0 +1,29 @@
+/** Codes the MCP client emits. */
+
+export const mcpCodes = [
+  'mcp-not-connected',
+  'mcp-start-failed',
+  'mcp-tool-failed',
+  'config-invalid',
+  'mcp-reference-unknown',
+  'mcp-reference-invalid',
+] as const
+
+/** An MCP client failure. Callers match `code`. */
+export type McpCode = (typeof mcpCodes)[number]
+
+/** Failure from `ctx.mcp`. The message is for a person. Secrets are not included. */
+export class McpError extends Error {
+  readonly code: McpCode
+
+  /**
+   * @param code - one of {@link mcpCodes}
+   * @param message - human text; not the match key
+   * @param options - optional `cause`
+   */
+  constructor(code: McpCode, message: string, options?: { cause?: unknown }) {
+    super(message, options)
+    this.name = 'McpError'
+    this.code = code
+  }
+}

package/src/config.ts

@@ -0,0 +1,52 @@
+import { McpError } from './codes.ts'
+
+/** One configured external server. */
+export type McpServerSpec =
+  | { command: string; args?: string[]; env?: Record<string, string> }
+  | { url: string; transport?: 'sse' | 'streamable-http'; headers?: Record<string, string> }
+
+/**
+ * Admit `mcp.json`. A missing value is zero servers. A present invalid value throws.
+ * An `mcpServers` wrapper is accepted. An entry named `settings` is skipped.
+ * @param value - parsed JSON, or `undefined` when the file is absent
+ */
+export function resolveMcpConfig(value: unknown): Record<string, McpServerSpec> {
+  if (value === undefined) return {}
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new McpError('config-invalid', 'mcp.json must be an object')
+  }
+  const record = value as Record<string, unknown>
+  const source = isObject(record.mcpServers) ? record.mcpServers : record
+  const servers: Record<string, McpServerSpec> = {}
+  for (const [id, entry] of Object.entries(source)) {
+    if (id === 'settings') continue
+    if (!isObject(entry)) throw new McpError('config-invalid', `mcp server ${id} must be an object`)
+    if (typeof entry.command === 'string') {
+      servers[id] = {
+        command: entry.command,
+        ...Array.isArray(entry.args) ? { args: entry.args.filter((item): item is string => typeof item === 'string') } : {},
+        ...isStringRecord(entry.env) ? { env: entry.env } : {},
+      }
+      continue
+    }
+    if (typeof entry.url === 'string') {
+      const transport = entry.transport === 'sse' || entry.transport === 'streamable-http' ? entry.transport : undefined
+      servers[id] = {
+        url: entry.url,
+        ...transport === undefined ? {} : { transport },
+        ...isStringRecord(entry.headers) ? { headers: entry.headers } : {},
+      }
+      continue
+    }
+    throw new McpError('config-invalid', `mcp server ${id} needs a command or a url`)
+  }
+  return servers
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+  return isObject(value) && Object.values(value).every(item => typeof item === 'string')
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+/** External MCP client. Not a model provider. @module @mohou/mcp-client */
+
+export const packageId = '@mohou/mcp-client' as const
+
+export { McpError, mcpCodes, type McpCode } from './codes.ts'
+export { resolveMcpConfig, type McpServerSpec } from './config.ts'
+export {
+  mcpReferenceKinds,
+  resolveServerMap,
+  resolveServerValues,
+  type McpReferenceKind,
+  type McpReferenceSources,
+} from './references.ts'
+export { McpClient } from './client.ts'
+export { isCredential, looksLikeCredential, maskCredential, mayHoldCredential, namesCredential } from './secrets.ts'

package/src/references.ts

@@ -0,0 +1,121 @@
+import { McpError } from './codes.ts'
+import type { McpServerSpec } from './config.ts'
+
+/**
+ * One named value a reference can name, or `undefined` when nothing holds that name.
+ * A credential provider is read per call, so a lookup may be async.
+ */
+export type McpReferenceLookup = (name: string) => string | undefined | Promise<string | undefined>
+
+/**
+ * Where a reference gets its value. Two lookups, bound by the caller: the ambient environment and
+ * whatever holds the credentials. This module knows no file, no keychain, and no provider package,
+ * so another credential implementation replaces the binding and not the resolver.
+ */
+export interface McpReferenceSources {
+  env: McpReferenceLookup
+  credential: McpReferenceLookup
+}
+
+/** Kinds a value may reference. A reference that is neither is literal text. */
+export const mcpReferenceKinds = ['env', 'credential'] as const
+
+export type McpReferenceKind = (typeof mcpReferenceKinds)[number]
+
+/**
+ * Replace every `${env:NAME}` and `${credential:NAME}` in one server spec.
+ * A spec without a reference comes back equal to its input; the input is never changed.
+ * The config file keeps the references. Only the copy handed to the client carries values.
+ * @param spec - one admitted server spec
+ * @param sources - the lookups the caller binds
+ * @param label - server id, used in a failure message only
+ */
+export async function resolveServerValues(
+  spec: McpServerSpec,
+  sources: McpReferenceSources,
+  label?: string,
+): Promise<McpServerSpec> {
+  if ('command' in spec) {
+    const args = spec.args === undefined
+      ? {}
+      : { args: await Promise.all(spec.args.map((item, index) => replace(item, `args[${index}]`, sources, label))) }
+    return {
+      ...spec,
+      command: await replace(spec.command, 'command', sources, label),
+      ...args,
+      ...spec.env === undefined ? {} : { env: await replaceRecord(spec.env, 'env', sources, label) },
+    }
+  }
+  return {
+    ...spec,
+    url: await replace(spec.url, 'url', sources, label),
+    ...spec.headers === undefined ? {} : { headers: await replaceRecord(spec.headers, 'headers', sources, label) },
+  }
+}
+
+/**
+ * Resolve every server in one map. The label of a failure is that server's id.
+ * @param servers - admitted specs, keyed by server id
+ * @param sources - the lookups the caller binds
+ */
+export async function resolveServerMap(
+  servers: Record<string, McpServerSpec>,
+  sources: McpReferenceSources,
+): Promise<Record<string, McpServerSpec>> {
+  const entries = await Promise.all(Object.entries(servers)
+    .map(async ([id, spec]) => [id, await resolveServerValues(spec, sources, id)] as const))
+  return Object.fromEntries(entries)
+}
+
+async function replaceRecord(
+  record: Record<string, string>,
+  field: string,
+  sources: McpReferenceSources,
+  label: string | undefined,
+): Promise<Record<string, string>> {
+  const entries = await Promise.all(Object.entries(record).map(async ([key, value]) => {
+    return [key, await replace(value, `${field}.${key}`, sources, label)] as const
+  }))
+  return Object.fromEntries(entries)
+}
+
+async function replace(text: string, where: string, sources: McpReferenceSources, label: string | undefined): Promise<string> {
+  if (!text.includes('${')) return text
+  const whole = /\$\{(env|credential):([^}]*)\}/g
+  const opening = /\$\{(env|credential):/
+  let out = ''
+  let index = 0
+  let match: RegExpExecArray | null
+  while ((match = whole.exec(text)) !== null) {
+    if (opening.test(text.slice(index, match.index))) throw invalid(label, where)
+    out += text.slice(index, match.index)
+    out += await value(match[1] as McpReferenceKind, match[2]?.trim() ?? '', where, sources, label)
+    index = match.index + match[0].length
+  }
+  if (opening.test(text.slice(index))) throw invalid(label, where)
+  return out + text.slice(index)
+}
+
+/** A value that is absent, or empty, fails the load. An empty token is worse than a boot error. */
+async function value(
+  kind: McpReferenceKind,
+  name: string,
+  where: string,
+  sources: McpReferenceSources,
+  label: string | undefined,
+): Promise<string> {
+  if (name.length === 0) throw invalid(label, where)
+  const found = await (kind === 'env' ? sources.env(name) : sources.credential(name))
+  if (found !== undefined && found.length > 0) return found
+  throw new McpError('mcp-reference-unknown', kind === 'env'
+    ? `${at(label, where)} names an environment variable that is not set: ${name}`
+    : `${at(label, where)} names an unknown credential: ${name}`)
+}
+
+function invalid(label: string | undefined, where: string): McpError {
+  return new McpError('mcp-reference-invalid', `${at(label, where)} has a malformed reference`)
+}
+
+function at(label: string | undefined, where: string): string {
+  return label === undefined ? where : `${label} ${where}`
+}

package/src/secrets.ts

@@ -0,0 +1,81 @@
+/** Credential detection and masking for MCP config values. One home, so every caller agrees. */
+
+/**
+ * Broad name test for handing the ambient environment to a child process.
+ * A false positive only withholds one variable; a false negative leaks a key to a third-party
+ * server. Callers that display a value use {@link namesCredential} instead.
+ */
+const BROAD_NAME = /KEY|SECRET|TOKEN|PASSWORD/i
+
+/** A whole segment of the name says credential. camelCase splits at its case boundary first. */
+const CREDENTIAL_WORDS = [
+  'KEY', 'SECRET', 'TOKEN', 'PASSWORD', 'PASSWD', 'CREDENTIAL', 'CREDENTIALS',
+  'AUTH', 'AUTHORIZATION', 'PRIVATE', 'SIGNATURE', 'COOKIE', 'SESSION',
+]
+const CREDENTIAL_SEGMENT = new RegExp(`(^|_)(${CREDENTIAL_WORDS.join('|')})(_|$)`)
+
+/**
+ * A leading run that names the kind of credential: the scheme of the value, or the issuer's own
+ * prefix. None of it is secret, so a masked value keeps it and the caller still reads what it holds.
+ */
+const CREDENTIAL_LABELS = [
+  'bearer\\s+', 'basic\\s+', 'token\\s+', 'apikey\\s+', 'sk-', 'pk-', 'rk-', 'ghp_', 'gho_', 'ghu_',
+  'ghs_', 'github_pat_', 'glpat-', 'xox[abprs]-', 'AKIA', 'ASIA', 'eyJ', '-----BEGIN[A-Z ]*-----',
+]
+const CREDENTIAL_LABEL = new RegExp(`^(${CREDENTIAL_LABELS.join('|')})`, 'i')
+
+/** The shape that carries no label, so only its length gives it away. */
+const LONG_HEX = /^[0-9a-f]{32,}$/i
+
+/**
+ * Ambient name test for a child's environment. Broad on purpose: see {@link BROAD_NAME}.
+ * @param name - environment variable name
+ */
+export function mayHoldCredential(name: string): boolean {
+  return BROAD_NAME.test(name)
+}
+
+/**
+ * Whether a whole segment of this name says credential. `GITHUB_TOKEN`, `x-api-key`, `apiKey`, and
+ * `DB_PASSWORD` pass; `NODE_ENV`, `MONKEY`, and `AUTHOR` do not, so masking them hides nothing.
+ * @param name - environment variable or header name
+ */
+export function namesCredential(name: string): boolean {
+  return CREDENTIAL_SEGMENT.test(normalizeName(name))
+}
+
+/**
+ * Whether the value's own shape is a credential, whatever its name says.
+ * @param value - the value to judge
+ */
+export function looksLikeCredential(value: string): boolean {
+  return CREDENTIAL_LABEL.test(value) || LONG_HEX.test(value)
+}
+
+/**
+ * Whether this entry is a credential, and so must not travel back to a caller in the clear.
+ * Either signal is enough: a named key, or a value whose shape gives it away.
+ * @param name - environment variable or header name
+ * @param value - the value to judge
+ */
+export function isCredential(name: string, value: string): boolean {
+  return namesCredential(name) || looksLikeCredential(value)
+}
+
+/**
+ * The form a caller may see. A recognized label stays, so `Bearer …` still reads as a bearer token
+ * and `ghp_…` as a GitHub token; the body behind it keeps its first and last two characters, and
+ * below five characters none of it. `Bearer abcdefgh` becomes `Bearer ab*****gh`.
+ * @param value - the credential value
+ */
+export function maskCredential(value: string): string {
+  const label = CREDENTIAL_LABEL.exec(value)?.[0] ?? ''
+  const body = value.slice(label.length)
+  if (body.length === 0) return value
+  if (body.length < 5) return `${label}*****`
+  return `${label}${body.slice(0, 2)}*****${body.slice(-2)}`
+}
+
+function normalizeName(name: string): string {
+  return name.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toUpperCase().replace(/[^A-Z0-9]+/g, '_')
+}