@gemus/mcp-proxy 0.1.9 → 0.1.10

package/src/setup/codex.mjs

@@ -0,0 +1,110 @@
+import { spawn as spawnChild } from 'node:child_process'
+
+export const CANONICAL_MARKETPLACE_SOURCE = 'Gemus-AI/gemus-codex-plugin'
+export const CODEX_MARKETPLACE = 'gemus'
+export const CODEX_PLUGIN = 'gemus@gemus'
+
+const OPERATIONS = Object.freeze(Object.assign(Object.create(null), {
+  listMarketplaces: Object.freeze(['plugin', 'marketplace', 'list', '--json']),
+  listPlugins: Object.freeze(['plugin', 'list', '--available', '--json']),
+  addMarketplace: Object.freeze(['plugin', 'marketplace', 'add', CANONICAL_MARKETPLACE_SOURCE]),
+  upgradeMarketplace: Object.freeze(['plugin', 'marketplace', 'upgrade', CODEX_MARKETPLACE]),
+  addPlugin: Object.freeze(['plugin', 'add', CODEX_PLUGIN, '--json']),
+}))
+
+const WINDOWS_COMMANDS = Object.freeze(Object.assign(Object.create(null), {
+  listMarketplaces: '"codex.cmd" plugin marketplace list --json',
+  listPlugins: '"codex.cmd" plugin list --available --json',
+  addMarketplace: '"codex.cmd" plugin marketplace add Gemus-AI/gemus-codex-plugin',
+  upgradeMarketplace: '"codex.cmd" plugin marketplace upgrade gemus',
+  addPlugin: '"codex.cmd" plugin add gemus@gemus --json',
+}))
+
+function own(object, key) { return Object.prototype.hasOwnProperty.call(object, key) }
+function scrubGemusEnvironment(env) { return Object.fromEntries(Object.entries(env).filter(([name]) => !/^gemus_(?:key|url)$/i.test(name))) }
+
+function spawnOperation(spawn, label, command, args, options) {
+  return new Promise((resolve, reject) => {
+    let child
+    try { child = spawn(command, args, options) } catch { reject(new Error(`Codex ${label} failed (exit 127).`)); return }
+    let stdout = ''
+    child.stdout?.on('data', (chunk) => { stdout += String(chunk) })
+    child.once('error', () => reject(new Error(`Codex ${label} failed (exit 127).`)))
+    child.once('exit', (code) => code === 0 ? resolve(stdout) : reject(new Error(`Codex ${label} failed (exit ${Number.isInteger(code) ? code : 1}).`)))
+  })
+}
+
+export function createCodexRunner({ platform = process.platform, spawn = spawnChild, env = process.env, comspec = env.ComSpec ?? env.COMSPEC ?? 'cmd.exe' } = {}) {
+  if (platform !== 'win32' && platform !== 'darwin') throw new Error('Gemus Companion setup supports only Windows and macOS.')
+  const childEnv = scrubGemusEnvironment(env)
+  return async (operation) => {
+    if (!own(OPERATIONS, operation)) throw new Error('Unsupported Codex setup operation.')
+    if (platform === 'win32') return spawnOperation(spawn, operation, comspec, ['/d', '/s', '/c', WINDOWS_COMMANDS[operation]], { env: childEnv, stdio: ['ignore', 'pipe', 'ignore'], windowsVerbatimArguments: true })
+    return spawnOperation(spawn, operation, 'codex', OPERATIONS[operation], { env: childEnv, stdio: ['ignore', 'pipe', 'ignore'] })
+  }
+}
+
+function json(raw, label) { try { return JSON.parse(raw) } catch { throw new Error(`Codex ${label} returned invalid JSON.`) } }
+function canonicalGitSource(sourceType, source) {
+  if (typeof sourceType !== 'string' || sourceType.toLowerCase() !== 'git' || typeof source !== 'string') return undefined
+  let candidate = source.trim()
+  if (/^git@github\.com:/i.test(candidate)) candidate = candidate.replace(/^git@github\.com:/i, '')
+  else if (/^https?:\/\/github\.com\//i.test(candidate)) candidate = candidate.replace(/^https?:\/\/github\.com\//i, '')
+  candidate = candidate.replace(/^\/+|\.git\/?$/gi, '').toLowerCase()
+  return candidate === 'gemus-ai/gemus-codex-plugin' ? CANONICAL_MARKETPLACE_SOURCE : undefined
+}
+function marketplaceRecord(value) {
+  if (!value || typeof value !== 'object' || typeof value.name !== 'string' || !value.marketplaceSource || typeof value.marketplaceSource !== 'object') throw new Error('Codex returned an unsupported marketplace record.')
+  const { sourceType, source } = value.marketplaceSource
+  if (typeof sourceType !== 'string' || typeof source !== 'string') throw new Error('Codex returned an unsupported marketplace record.')
+  return { ...value, canonicalSource: canonicalGitSource(sourceType, source) }
+}
+function pluginRecord(value) {
+  if (!value || typeof value !== 'object' || typeof value.pluginId !== 'string' || typeof value.name !== 'string' || typeof value.marketplaceName !== 'string' || typeof value.version !== 'string' || !value.version || typeof value.installed !== 'boolean' || !value.marketplaceSource || typeof value.marketplaceSource !== 'object') throw new Error('Codex returned an unsupported plugin record.')
+  const { sourceType, source } = value.marketplaceSource
+  if (typeof sourceType !== 'string' || typeof source !== 'string') throw new Error('Codex returned an unsupported plugin record.')
+  return { ...value, canonicalSource: canonicalGitSource(sourceType, source) }
+}
+function marketplaces(raw) {
+  const value = json(raw, 'marketplace list')
+  if (!value || typeof value !== 'object' || !Array.isArray(value.marketplaces)) throw new Error('Codex returned an unsupported marketplace JSON envelope.')
+  return value.marketplaces.map(marketplaceRecord)
+}
+function plugins(raw) {
+  const value = json(raw, 'plugin list')
+  if (!value || typeof value !== 'object' || !Array.isArray(value.installed) || !Array.isArray(value.available)) throw new Error('Codex returned an unsupported plugin JSON envelope.')
+  return { installed: value.installed.map(pluginRecord), available: value.available.map(pluginRecord) }
+}
+function advertisedPlugin(raw) {
+  const value = json(raw, 'plugin add')
+  const record = value.plugin ?? value
+  if (!record || typeof record !== 'object' || typeof record.pluginId !== 'string' || typeof record.name !== 'string' || typeof record.marketplaceName !== 'string' || typeof record.version !== 'string' || !record.version || typeof record.installedPath !== 'string' || typeof record.authPolicy !== 'string') throw new Error('Codex returned an unsupported plugin add result.')
+  if (record.pluginId !== CODEX_PLUGIN || record.marketplaceName.toLowerCase() !== CODEX_MARKETPLACE) throw new Error('Codex returned an untrusted plugin add result.')
+  return record
+}
+function gemusMarketplace(records) {
+  const matches = records.filter((record) => record.name.toLowerCase() === CODEX_MARKETPLACE)
+  if (matches.length > 1) throw new Error('Gemus marketplace is ambiguous; setup stopped before making changes.')
+  return matches[0]
+}
+function assertMarketplace(records) {
+  const record = gemusMarketplace(records)
+  if (!record) return undefined
+  if (!record.canonicalSource) throw new Error('The Gemus marketplace does not use the trusted source; setup stopped before making changes.')
+  return record
+}
+function verifiedPlugin(records, version) { return records.installed.find((record) => record.pluginId === CODEX_PLUGIN && record.installed && record.marketplaceName.toLowerCase() === CODEX_MARKETPLACE && record.canonicalSource && record.version === version) }
+
+export async function reconcileCodex({ run = createCodexRunner() } = {}) {
+  const initialMarketplaces = marketplaces(await run('listMarketplaces'))
+  const initialPlugins = plugins(await run('listPlugins'))
+  const initialMarketplace = assertMarketplace(initialMarketplaces)
+  if (initialMarketplace) await run('upgradeMarketplace'); else await run('addMarketplace')
+  const reconciledMarketplace = assertMarketplace(marketplaces(await run('listMarketplaces')))
+  if (!reconciledMarketplace) throw new Error('Codex marketplace postcondition failed; plugin was not added.')
+  const advertised = advertisedPlugin(await run('addPlugin'))
+  const finalPlugins = plugins(await run('listPlugins'))
+  const installed = verifiedPlugin(finalPlugins, advertised.version)
+  if (!installed) throw new Error('Codex plugin postcondition failed.')
+  return { marketplace: reconciledMarketplace, plugin: installed, pluginInstalled: Boolean(verifiedPlugin(initialPlugins, advertised.version)) }
+}

package/src/setup/config.mjs

@@ -0,0 +1,530 @@
+const LEGACY_ROOT = ['mcp_servers', 'gemus']
+const COMPANION_ROOT = ['plugins', 'gemus@gemus', 'mcp_servers', 'gemus']
+
+function splitLines(source) {
+  const lines = []
+  const expression = /.*?(?:\r\n|\n|\r|$)/g
+  let match
+  while ((match = expression.exec(source))) {
+    if (match[0] === '') break
+    const raw = match[0]
+    lines.push({ raw, text: raw.replace(/\r\n|\n|\r$/, '') })
+  }
+  return lines
+}
+
+function commentIndex(text) {
+  let quote = null
+  let escaped = false
+  for (let index = 0; index < text.length; index += 1) {
+    const character = text[index]
+    if (quote === '"' && escaped) {
+      escaped = false
+      continue
+    }
+    if (quote === '"' && character === '\\') {
+      escaped = true
+      continue
+    }
+    if (character === quote) {
+      quote = null
+      continue
+    }
+    if (!quote && (character === '"' || character === "'")) {
+      quote = character
+      continue
+    }
+    if (!quote && character === '#') return index
+  }
+  return -1
+}
+
+function withoutComment(text) {
+  const index = commentIndex(text)
+  return index === -1 ? text : text.slice(0, index)
+}
+
+function parseSegments(value) {
+  const segments = []
+  let index = 0
+  const skipWhitespace = () => {
+    while (/\s/.test(value[index] ?? '')) index += 1
+  }
+  while (index < value.length) {
+    skipWhitespace()
+    if (index >= value.length) break
+    let segment = ''
+    const quote = value[index]
+    if (quote === '"' || quote === "'") {
+      index += 1
+      const start = index
+      let escaped = false
+      while (index < value.length) {
+        const character = value[index]
+        if (quote === '"' && escaped) {
+          escaped = false
+        } else if (quote === '"' && character === '\\') {
+          escaped = true
+        } else if (character === quote) {
+          break
+        }
+        index += 1
+      }
+      if (value[index] !== quote) return undefined
+      const encoded = value.slice(start, index)
+      segment = quote === '"' ? decodeBasicKey(encoded) : encoded
+      if (segment === undefined) return undefined
+      index += 1
+    } else {
+      const match = /^[A-Za-z0-9_-]+/.exec(value.slice(index))
+      if (!match) return undefined
+      segment = match[0]
+      index += segment.length
+    }
+    segments.push(segment)
+    skipWhitespace()
+    if (index === value.length) break
+    if (value[index] !== '.') return undefined
+    index += 1
+  }
+  return segments.length ? segments : undefined
+}
+
+function decodeBasicKey(encoded) {
+  let decoded = ''
+  for (let index = 0; index < encoded.length; index += 1) {
+    const character = encoded[index]
+    if (character !== '\\') {
+      decoded += character
+      continue
+    }
+    const escape = encoded[++index]
+    const escapes = { b: '\b', t: '\t', n: '\n', f: '\f', r: '\r', '"': '"', '\\': '\\' }
+    if (escape in escapes) {
+      decoded += escapes[escape]
+      continue
+    }
+    const width = escape === 'u' ? 4 : escape === 'U' ? 8 : undefined
+    if (!width) return undefined
+    const hex = encoded.slice(index + 1, index + 1 + width)
+    if (!new RegExp(`^[0-9A-Fa-f]{${width}}$`).test(hex)) return undefined
+    const codePoint = Number.parseInt(hex, 16)
+    if (codePoint > 0x10ffff || (codePoint >= 0xd800 && codePoint <= 0xdfff)) return undefined
+    decoded += String.fromCodePoint(codePoint)
+    index += width
+  }
+  return decoded
+}
+
+function parseHeader(text) {
+  const source = text.replace(/^\uFEFF/, '')
+  let index = 0
+  while (/\s/.test(source[index] ?? '')) index += 1
+  const array = source.startsWith('[[', index)
+  if (!array && source[index] !== '[') return undefined
+  index += array ? 2 : 1
+  const start = index
+  let quote = undefined
+  let escaped = false
+  while (index < source.length) {
+    const character = source[index]
+    if (quote === '"' && escaped) {
+      escaped = false
+    } else if (quote === '"' && character === '\\') {
+      escaped = true
+    } else if (character === quote) {
+      quote = undefined
+    } else if (!quote && (character === '"' || character === "'")) {
+      quote = character
+    } else if (!quote && character === ']') {
+      if (array && source[index + 1] !== ']') return undefined
+      const end = index
+      index += array ? 2 : 1
+      const trailing = source.slice(index)
+      if (!/^\s*(?:#.*)?$/.test(trailing)) return undefined
+      const segments = parseSegments(source.slice(start, end))
+      return segments ? { segments, array } : undefined
+    }
+    index += 1
+  }
+  return undefined
+}
+
+function isPotentiallyRelevantHeader(text) {
+  const source = text.replace(/^\uFEFF/, '').trimStart()
+  if (!source.startsWith('[')) return false
+  const decoded = source.replace(/\\u[0-9A-Fa-f]{4}|\\U[0-9A-Fa-f]{8}/g, (escape) => (
+    decodeBasicKey(escape) ?? escape
+  ))
+  return decoded.includes('mcp_servers')
+    && (decoded.includes('gemus') || source.includes('\\u') || source.includes('\\U'))
+}
+
+function startsWith(segments, root) {
+  return segments.length >= root.length && root.every((part, index) => segments[index] === part)
+}
+
+function isRelevantRoot(segments) {
+  return startsWith(segments, LEGACY_ROOT) || startsWith(segments, COMPANION_ROOT)
+}
+
+function samePath(segments, root) {
+  return segments.length === root.length && startsWith(segments, root)
+}
+
+function multilineDelimiter(text) {
+  const content = withoutComment(text)
+  const basic = (content.match(/"""/g) ?? []).length
+  const literal = (content.match(/'''/g) ?? []).length
+  if (basic % 2) return '"""'
+  if (literal % 2) return "'''"
+  return undefined
+}
+
+function closesMultilineBasicString(text) {
+  for (let index = 0; index < text.length;) {
+    if (text[index] !== '"') {
+      index += 1
+      continue
+    }
+    const runStart = index
+    while (text[index] === '"') index += 1
+    let backslashes = 0
+    for (let before = runStart - 1; before >= 0 && text[before] === '\\'; before -= 1) {
+      backslashes += 1
+    }
+    const escapedQuotes = backslashes % 2
+    if (index - runStart - escapedQuotes >= 3) return true
+  }
+  return false
+}
+
+function closesMultilineString(text, delimiter) {
+  return delimiter === '"""'
+    ? closesMultilineBasicString(text)
+    : text.includes(delimiter)
+}
+
+function lex(source) {
+  const lines = splitLines(source)
+  const headers = []
+  const codeLines = new Set()
+  let multiline = undefined
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index]
+    if (!multiline) {
+      codeLines.add(index)
+      const header = parseHeader(line.text)
+      if (header) headers.push({ index, ...header })
+      const opener = multilineDelimiter(line.text)
+      if (opener) multiline = opener
+    } else if (closesMultilineString(line.text, multiline)) {
+      multiline = undefined
+    }
+  }
+  return { lines, headers, codeLines }
+}
+
+function assignment(text) {
+  const content = withoutComment(text)
+  const match = /^\s*([^=]+?)\s*=\s*(.*?)\s*$/.exec(content)
+  if (!match) return undefined
+  const segments = parseSegments(match[1])
+  return segments ? { segments, value: match[2] } : undefined
+}
+
+function inlineTableEntries(value) {
+  const content = value.trim()
+  if (!content.startsWith('{')) return undefined
+  const entries = []
+  let start = 1
+  let braces = 1
+  let brackets = 0
+  let quote = undefined
+  let escaped = false
+  for (let index = 1; index < content.length; index += 1) {
+    const character = content[index]
+    if (quote === '"' && escaped) {
+      escaped = false
+      continue
+    }
+    if (quote === '"' && character === '\\') {
+      escaped = true
+      continue
+    }
+    if (character === quote) {
+      quote = undefined
+      continue
+    }
+    if (!quote && (character === '"' || character === "'")) {
+      quote = character
+      continue
+    }
+    if (quote) continue
+    if (character === '#') return undefined
+    if (character === '{') braces += 1
+    else if (character === '}') {
+      braces -= 1
+      if (braces === 0) {
+        if (brackets !== 0 || content.slice(index + 1).trim() !== '') return undefined
+        const entry = content.slice(start, index).trim()
+        if (entry) entries.push(entry)
+        else if (entries.length > 0) return undefined
+        return entries
+      }
+    } else if (character === '[') brackets += 1
+    else if (character === ']') {
+      brackets -= 1
+      if (brackets < 0) return undefined
+    } else if (character === ',' && braces === 1 && brackets === 0) {
+      const entry = content.slice(start, index).trim()
+      if (!entry) return undefined
+      entries.push(entry)
+      start = index + 1
+    }
+    if (braces < 1) return undefined
+  }
+  return undefined
+}
+
+function inlineTableDefinesKey(value, key) {
+  const entries = inlineTableEntries(value)
+  if (!entries) return undefined
+  for (const entry of entries) {
+    const parsed = assignment(entry)
+    if (!parsed) return undefined
+    if (parsed.segments[0] === key) return true
+  }
+  return false
+}
+
+function relevantAssignment(activeHeader, parsed) {
+  const path = [...(activeHeader ?? []), ...parsed.segments]
+  if (activeHeader && startsWith(activeHeader, LEGACY_ROOT)) return undefined
+  const inlineTable = parsed.value.trimStart().startsWith('{')
+  for (const root of [LEGACY_ROOT, COMPANION_ROOT]) {
+    const definesRoot = samePath(path, root)
+    const dottedDescendant = parsed.segments.length > 1 && startsWith(path, root)
+    let overlappingInlineTable = inlineTable
+      && (startsWith(path, root) || startsWith(root, path))
+    if (overlappingInlineTable && root === LEGACY_ROOT && samePath(path, ['mcp_servers'])) {
+      overlappingInlineTable = inlineTableDefinesKey(parsed.value, 'gemus') !== false
+    }
+    if (definesRoot || dottedDescendant || overlappingInlineTable) return root
+  }
+  return undefined
+}
+
+function parseString(value) {
+  if (value.startsWith('"""') || value.startsWith("'''")) return undefined
+  if (value.startsWith('"')) {
+    try {
+      const parsed = JSON.parse(value)
+      return typeof parsed === 'string' ? parsed : undefined
+    } catch {
+      return undefined
+    }
+  }
+  if (value.startsWith("'") && value.endsWith("'") && value.length >= 2) {
+    return value.slice(1, -1)
+  }
+  return undefined
+}
+
+function subtreeRanges(headers, lineCount, root) {
+  const ranges = []
+  for (let headerIndex = 0; headerIndex < headers.length; headerIndex += 1) {
+    const header = headers[headerIndex]
+    if (!startsWith(header.segments, root)) continue
+    let end = lineCount
+    for (let nextIndex = headerIndex + 1; nextIndex < headers.length; nextIndex += 1) {
+      const next = headers[nextIndex]
+      if (!startsWith(next.segments, root)) {
+        end = next.index
+        break
+      }
+    }
+    ranges.push([header.index, end])
+  }
+  return ranges
+}
+
+function isHttpUrl(value) {
+  try {
+    const parsed = new URL(value)
+    return parsed.protocol === 'http:' || parsed.protocol === 'https:'
+  } catch {
+    return false
+  }
+}
+
+export function inspectCodexConfig(source) {
+  const { lines, headers, codeLines } = lex(source)
+  const headersByLine = new Map(headers.map((header) => [header.index, header]))
+  const issues = []
+  const legacyHeaders = headers.filter(({ segments }) => startsWith(segments, LEGACY_ROOT))
+  const companionHeaders = headers.filter(({ segments }) => (
+    segments.length === COMPANION_ROOT.length && startsWith(segments, COMPANION_ROOT)
+  ))
+  const values = new Map()
+  const valueCounts = new Map()
+  let legacyKeyWasPresent = false
+  let legacyAssignmentWasPresent = false
+  let activeHeader = undefined
+
+  for (const [index, line] of lines.entries()) {
+    if (!codeLines.has(index)) continue
+    const header = headersByLine.get(index)
+    if (header) {
+      activeHeader = header.segments
+      continue
+    }
+    const parsed = assignment(line.text)
+    const assignmentRoot = parsed ? relevantAssignment(activeHeader, parsed) : undefined
+    if (assignmentRoot) {
+      issues.push('unsupported Gemus inline or dotted assignment')
+      if (assignmentRoot === LEGACY_ROOT) legacyAssignmentWasPresent = true
+    }
+    if (!activeHeader || !startsWith(activeHeader, [...LEGACY_ROOT, 'env'])) continue
+    if (activeHeader.length !== 3 || !parsed || parsed.segments.length !== 1) continue
+    const key = parsed.segments[0]
+    if (key !== 'GEMUS_KEY' && key !== 'GEMUS_URL') continue
+    if (key === 'GEMUS_KEY') legacyKeyWasPresent = true
+    const count = (valueCounts.get(key) ?? 0) + 1
+    valueCounts.set(key, count)
+    if (count > 1) {
+      values.delete(key)
+      continue
+    }
+    const value = parseString(parsed.value)
+    if (value === undefined) continue
+    if (key === 'GEMUS_URL' && !isHttpUrl(value)) continue
+    values.set(key, value)
+  }
+
+  for (const [index, line] of lines.entries()) {
+    if (!codeLines.has(index)) continue
+    const content = line.text.replace(/^\uFEFF/, '').trimStart()
+    if (isPotentiallyRelevantHeader(content)) {
+      if (!parseHeader(line.text)) issues.push('malformed Gemus header')
+    }
+  }
+
+  for (const header of headers) {
+    if (header.array && isRelevantRoot(header.segments)) {
+      issues.push('unsupported Gemus array table')
+    }
+  }
+
+  const enabledValues = []
+  activeHeader = undefined
+  for (const [index, line] of lines.entries()) {
+    if (!codeLines.has(index)) continue
+    const header = headersByLine.get(index)
+    if (header) {
+      activeHeader = header.segments
+      continue
+    }
+    if (!activeHeader || activeHeader.length !== COMPANION_ROOT.length || !startsWith(activeHeader, COMPANION_ROOT)) continue
+    const parsed = assignment(line.text)
+    if (parsed?.segments.length === 1 && parsed.segments[0] === 'enabled') enabledValues.push(parsed.value.trim())
+  }
+
+  return {
+    hasLegacyGemus: legacyHeaders.length > 0 || legacyAssignmentWasPresent,
+    enabledPluginCompanion: companionHeaders.length > 0 && enabledValues.includes('true'),
+    legacyKey: values.get('GEMUS_KEY'),
+    legacyKeyWasPresent,
+    legacyUrl: values.get('GEMUS_URL'),
+    issues: [...new Set(issues)],
+    companionSectionCount: companionHeaders.length,
+    enabledValueCount: enabledValues.length,
+  }
+}
+
+function companionText(newline, preservedBody = '') {
+  const bodySeparator = preservedBody && !/(\r\n|\n|\r)$/.test(preservedBody) ? newline : ''
+  return `[plugins."gemus@gemus".mcp_servers.gemus]${newline}${preservedBody}${bodySeparator}enabled = true${newline}`
+}
+
+function standaloneComment(line) {
+  const index = commentIndex(line.text)
+  if (index === -1) return ''
+  const indentation = /^\s*/.exec(line.text)?.[0] ?? ''
+  return `${indentation}${line.text.slice(index)}${line.raw.slice(line.text.length)}`
+}
+
+function migrationResult(source, nextText, inspection) {
+  return {
+    changed: nextText !== source,
+    nextText,
+    text: nextText,
+    removedLegacy: inspection.hasLegacyGemus,
+    legacyKey: inspection.legacyKey,
+    legacyKeyWasPresent: inspection.legacyKeyWasPresent,
+    legacyUrl: inspection.legacyUrl,
+    enabledPluginCompanion: true,
+  }
+}
+
+export function planCodexConfigMigration(source) {
+  const inspection = inspectCodexConfig(source)
+  if (inspection.issues.length) {
+    throw new Error(`cannot safely migrate Gemus config: ${inspection.issues.join(', ')}`)
+  }
+
+  const alreadyCanonical = !inspection.hasLegacyGemus
+    && inspection.companionSectionCount === 1
+    && inspection.enabledValueCount === 1
+    && inspection.enabledPluginCompanion
+  if (alreadyCanonical) {
+    return migrationResult(source, source, inspection)
+  }
+
+  const bom = source.startsWith('\uFEFF') ? '\uFEFF' : ''
+  const bodySource = bom ? source.slice(1) : source
+  const { lines, headers, codeLines } = lex(bodySource)
+  const removed = new Set()
+  for (const [start, end] of subtreeRanges(headers, lines.length, LEGACY_ROOT)) {
+    for (let index = start; index < end; index += 1) removed.add(index)
+  }
+
+  const directCompanionHeaders = headers
+    .map((header, index) => ({ ...header, headerIndex: index }))
+    .filter(({ segments }) => segments.length === COMPANION_ROOT.length && startsWith(segments, COMPANION_ROOT))
+  const newline = bodySource.includes('\r\n') ? '\r\n' : bodySource.includes('\r') ? '\r' : '\n'
+  let companionBody = ''
+  for (const header of directCompanionHeaders) {
+    const end = headers[header.headerIndex + 1]?.index ?? lines.length
+    for (let index = header.index; index < end; index += 1) {
+      removed.add(index)
+      if (index === header.index) {
+        companionBody += standaloneComment(lines[index])
+        continue
+      }
+      const parsed = codeLines.has(index) ? assignment(lines[index].text) : undefined
+      if (parsed?.segments.length === 1 && parsed.segments[0] === 'enabled') {
+        companionBody += standaloneComment(lines[index])
+        continue
+      }
+      companionBody += lines[index].raw
+    }
+  }
+
+  const block = companionText(newline, companionBody)
+  const insertionIndex = directCompanionHeaders[0]?.index
+  let body = ''
+  for (const [index, line] of lines.entries()) {
+    if (index === insertionIndex) body += block
+    if (!removed.has(index)) body += line.raw
+  }
+  if (insertionIndex === undefined) {
+    const separator = body === '' ? '' : /(\r\n|\n|\r)$/.test(body) ? newline : `${newline}${newline}`
+    body += `${separator}${block}`
+  }
+
+  const hadTrailingNewline = bodySource === '' || /(\r\n|\n|\r)$/.test(bodySource)
+  if (!hadTrailingNewline) body = body.replace(/(\r\n|\n|\r)$/, '')
+  const nextText = `${bom}${body}`
+  return migrationResult(source, nextText, inspection)
+}