@paradigma-inc/flywheel 0.1.115 → 0.1.134

package/src/mcp-writer.mjs

@@ -1,161 +1,155 @@
 import { access, readFile } from "node:fs/promises";
 import { load as loadYaml, dump as dumpYaml } from "js-yaml";
-import { secureFileMode, writeSecureFile } from "./secure-write.mjs";
+import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
+import { preparePrivateConfigPath, secureFileMode, writeSecureFile } from "./runtime/vendor/flywheel-cli-dist/auth/secure-write.js";
+import { scanTomlLines } from "./toml-lines.mjs";
 
 function stripJsonComments(text) {
-  let result = "";
-  let i = 0;
-  while (i < text.length) {
-    if (text[i] === '"') {
-      const start = i++;
-      while (i < text.length && text[i] !== '"') {
-        if (text[i] === "\\") i += 1;
-        i += 1;
-      }
-      result += text.slice(start, ++i);
-    } else if (text[i] === "/" && text[i + 1] === "/") {
-      i += 2;
-      while (i < text.length && text[i] !== "\n") i += 1;
-    } else if (text[i] === "/" && text[i + 1] === "*") {
-      i += 2;
-      while (i < text.length && !(text[i] === "*" && text[i + 1] === "/"))
-        i += 1;
-      i += 2;
-    } else {
-      result += text[i];
-      i += 1;
-    }
+ let result = "";
+ let i = 0;
+ while (i < text.length) {
+  if (text[i] === '"') {
+   const start = i++;
+   while (i < text.length && text[i] !== '"') {
+    if (text[i] === "\\") i += 1;
+    i += 1;
+   }
+   result += text.slice(start, ++i);
+  } else if (text[i] === "/" && text[i + 1] === "/") {
+   i += 2;
+   while (i < text.length && text[i] !== "\n") i += 1;
+  } else if (text[i] === "/" && text[i + 1] === "*") {
+   i += 2;
+   while (i < text.length && !(text[i] === "*" && text[i + 1] === "/"))
+    i += 1;
+   i += 2;
+  } else {
+   result += text[i];
+   i += 1;
   }
-  return result;
+ }
+ return result;
 }
 
-function normalizeLineEndings(text) {
-  return text.replace(/\r\n/g, "\n");
-}
 
 function stripTomlInlineComment(valueText) {
-  let inSingleQuotedString = false;
-  let inDoubleQuotedString = false;
-  let escapeNextChar = false;
-
-  for (let index = 0; index < valueText.length; index += 1) {
-    const char = valueText[index];
-
-    if (escapeNextChar) {
-      escapeNextChar = false;
-      continue;
-    }
-
-    if (inDoubleQuotedString && char === "\\") {
-      escapeNextChar = true;
-      continue;
-    }
-
-    if (!inDoubleQuotedString && char === "'") {
-      inSingleQuotedString = !inSingleQuotedString;
-      continue;
-    }
-
-    if (!inSingleQuotedString && char === '"') {
-      inDoubleQuotedString = !inDoubleQuotedString;
-      continue;
-    }
-
-    if (!inSingleQuotedString && !inDoubleQuotedString && char === "#") {
-      return valueText.slice(0, index).trim();
-    }
-  }
+ let inSingleQuotedString = false;
+ let inDoubleQuotedString = false;
+ let escapeNextChar = false;
 
-  return valueText.trim();
-}
+ for (let index = 0; index < valueText.length; index += 1) {
+  const char = valueText[index];
 
-export function parseTomlStringValue(valueText) {
-  const stripped = stripTomlInlineComment(valueText);
-  if (!stripped) {
-    return null;
+  if (escapeNextChar) {
+   escapeNextChar = false;
+   continue;
   }
 
-  if (stripped.startsWith('"""') && stripped.endsWith('"""') && stripped.length >= 6) {
-    return stripped.slice(3, -3);
+  if (inDoubleQuotedString && char === "\\") {
+   escapeNextChar = true;
+   continue;
   }
 
-  if (stripped.startsWith("'''") && stripped.endsWith("'''") && stripped.length >= 6) {
-    return stripped.slice(3, -3);
+  if (!inDoubleQuotedString && char === "'") {
+   inSingleQuotedString = !inSingleQuotedString;
+   continue;
   }
 
-  if (stripped.startsWith('"') && stripped.endsWith('"')) {
-    try {
-      return JSON.parse(stripped);
-    } catch {
-      return stripped.slice(1, -1);
-    }
+  if (!inSingleQuotedString && char === '"') {
+   inDoubleQuotedString = !inDoubleQuotedString;
+   continue;
   }
 
-  if (stripped.startsWith("'") && stripped.endsWith("'")) {
-    return stripped.slice(1, -1);
+  if (!inSingleQuotedString && !inDoubleQuotedString && char === "#") {
+   return valueText.slice(0, index).trim();
   }
+ }
 
-  return stripped;
+ return valueText.trim();
 }
 
-export function parseTomlSectionName(lineText) {
-  const withoutComment = stripTomlInlineComment(String(lineText || "").trim());
-  const sectionMatch = withoutComment.match(/^\[(.+)\]$/);
-  return sectionMatch ? sectionMatch[1] : null;
-}
+export function parseTomlStringValue(valueText) {
+ const stripped = stripTomlInlineComment(valueText);
+ if (!stripped) {
+  return null;
+ }
 
-export async function readJsonConfig(filePath) {
-  let raw;
+ if (stripped.startsWith('"""') && stripped.endsWith('"""') && stripped.length >= 6) {
+  return stripped.slice(3, -3);
+ }
+
+ if (stripped.startsWith("'''") && stripped.endsWith("'''") && stripped.length >= 6) {
+  return stripped.slice(3, -3);
+ }
+
+ if (stripped.startsWith('"') && stripped.endsWith('"')) {
   try {
-    raw = await readFile(filePath, "utf8");
+   return JSON.parse(stripped);
   } catch {
-    return {};
+   return stripped.slice(1, -1);
   }
-  const trimmed = raw.trim();
-  if (!trimmed) return {};
-  return JSON.parse(stripJsonComments(trimmed));
+ }
+
+ if (stripped.startsWith("'") && stripped.endsWith("'")) {
+  return stripped.slice(1, -1);
+ }
+
+ return stripped;
+}
+
+
+export async function readJsonConfig(filePath) {
+ let raw;
+ try {
+  raw = await readFile(filePath, "utf8");
+ } catch {
+  return {};
+ }
+ const trimmed = raw.trim();
+ if (!trimmed) return {};
+ return JSON.parse(stripJsonComments(trimmed));
 }
 
 export async function writeJsonConfig(filePath, config) {
-  await writeSecureFile(filePath, `${JSON.stringify(config, null, 2)}\n`);
+ await writeSecureFile(filePath, `${JSON.stringify(config, null, 2)}\n`);
 }
 
 export async function readYamlConfig(filePath) {
-  let raw;
-  try {
-    raw = await readFile(filePath, "utf8");
-  } catch {
-    return {};
-  }
-  const trimmed = raw.trim();
-  if (!trimmed) return {};
-
-  try {
-    const parsed = loadYaml(trimmed);
-    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-      return parsed;
-    }
-    return {};
-  } catch {
-    return {};
+ let raw;
+ try {
+  raw = await readFile(filePath, "utf8");
+ } catch {
+  return {};
+ }
+ const trimmed = raw.trim();
+ if (!trimmed) return {};
+
+ try {
+  const parsed = loadYaml(trimmed);
+  if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+   return parsed;
   }
+  return {};
+ } catch {
+  return {};
+ }
 }
 
 export async function writeYamlConfig(filePath, config) {
-  await writeSecureFile(filePath, dumpYaml(config, { noRefs: true }));
+ await writeSecureFile(filePath, dumpYaml(config, { noRefs: true }));
 }
 
 export async function resolveMcpPath(candidates) {
-  for (const candidate of candidates) {
-    try {
-      // eslint-disable-next-line no-await-in-loop
-      await access(candidate);
-      return candidate;
-    } catch {
-      // keep searching
-    }
+ for (const candidate of candidates) {
+  try {
+   // eslint-disable-next-line no-await-in-loop
+   await access(candidate);
+   return candidate;
+  } catch {
+   // keep searching
   }
-  return candidates[0];
+ }
+ return candidates[0];
 }
 
 /**
@@ -182,28 +176,28 @@ export async function resolveMcpPath(candidates) {
  * Returns null when no recognizable URL key is present.
  */
 export function readEntryServerUrl(entry) {
-  if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
-    return null;
-  }
-  // Empty / whitespace-only strings are placeholder shapes (half-populated
-  // host writers, hand-edited configs). Returning "" from here would satisfy
-  // downstream `typeof === "string"` checks but break equality comparisons in
-  // idempotent setup, drift detection, and uninstall enumeration — the live
-  // entry would be misclassified as missing. Only non-blank strings count.
-  //
-  // Trim-and-return-trimmed: callers compare the result against a canonical
-  // target via strict equality. Returning the raw field would re-introduce
-  // the false mismatch on hand-edited configs that carry leading/trailing
-  // whitespace or a trailing newline around the value.
-  const httpUrl = typeof entry.httpUrl === "string" ? entry.httpUrl.trim() : "";
-  if (httpUrl.length > 0) {
-    return httpUrl;
-  }
-  const url = typeof entry.url === "string" ? entry.url.trim() : "";
-  if (url.length > 0) {
-    return url;
-  }
+ if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
   return null;
+ }
+ // Empty / whitespace-only strings are placeholder shapes (half-populated
+ // host writers, hand-edited configs). Returning "" from here would satisfy
+ // downstream `typeof === "string"` checks but break equality comparisons in
+ // idempotent setup, drift detection, and uninstall enumeration — the live
+ // entry would be misclassified as missing. Only non-blank strings count.
+ //
+ // Trim-and-return-trimmed: callers compare the result against a canonical
+ // target via strict equality. Returning the raw field would re-introduce
+ // the false mismatch on hand-edited configs that carry leading/trailing
+ // whitespace or a trailing newline around the value.
+ const httpUrl = typeof entry.httpUrl === "string" ? entry.httpUrl.trim() : "";
+ if (httpUrl.length > 0) {
+  return httpUrl;
+ }
+ const url = typeof entry.url === "string" ? entry.url.trim() : "";
+ if (url.length > 0) {
+  return url;
+ }
+ return null;
 }
 
 /**
@@ -223,354 +217,338 @@ export function readEntryServerUrl(entry) {
  * circuit would leave the stale Authorization header behind.
  */
 export function readEntryAuthMode(entry) {
-  if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
-    return "oauth";
-  }
-  const headers = entry.headers;
-  if (
-    headers &&
-    typeof headers === "object" &&
-    !Array.isArray(headers) &&
-    typeof headers.Authorization === "string"
-  ) {
-    return "api-key";
-  }
+ if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
   return "oauth";
+ }
+ const headers = entry.headers;
+ if (
+  headers &&
+  typeof headers === "object" &&
+  !Array.isArray(headers) &&
+  typeof headers.Authorization === "string"
+ ) {
+  return "api-key";
+ }
+ return "oauth";
 }
 
 function keyPath(configKey) {
-  return Array.isArray(configKey) ? configKey : [configKey];
+ return Array.isArray(configKey) ? configKey : [configKey];
 }
 
 function readConfigSection(config, configKey) {
-  const pathParts = keyPath(configKey);
-  let current = config && typeof config === "object" ? config : {};
-  for (const part of pathParts) {
-    if (
-      !current ||
-      typeof current !== "object" ||
-      Array.isArray(current) ||
-      !(part in current)
-    ) {
-      return {};
-    }
-    const next = current[part];
-    if (!next || typeof next !== "object" || Array.isArray(next)) {
-      return {};
-    }
-    current = next;
+ const pathParts = keyPath(configKey);
+ let current = config && typeof config === "object" ? config : {};
+ for (const part of pathParts) {
+  if (
+   !current ||
+   typeof current !== "object" ||
+   Array.isArray(current) ||
+   !(part in current)
+  ) {
+   return {};
+  }
+  const next = current[part];
+  if (!next || typeof next !== "object" || Array.isArray(next)) {
+   return {};
   }
-  return current;
+  current = next;
+ }
+ return current;
 }
 
 export function readNamedConfigEntry(config, configKey, serverName) {
-  const section = readConfigSection(config, configKey);
-  const entry = section[serverName];
-  if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
-    return null;
-  }
-  return entry;
+ const section = readConfigSection(config, configKey);
+ const entry = section[serverName];
+ if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+  return null;
+ }
+ return entry;
 }
 
 function writeConfigSection(config, configKey, section) {
-  const pathParts = keyPath(configKey);
-  if (pathParts.length === 0) return config || {};
-
-  const root =
-    config && typeof config === "object" && !Array.isArray(config)
-      ? { ...config }
-      : {};
-  let cursor = root;
-
-  for (let index = 0; index < pathParts.length - 1; index += 1) {
-    const part = pathParts[index];
-    const existing = cursor[part];
-    cursor[part] =
-      existing && typeof existing === "object" && !Array.isArray(existing)
-        ? { ...existing }
-        : {};
-    cursor = cursor[part];
-  }
-  cursor[pathParts[pathParts.length - 1]] = section;
-  return root;
+ const pathParts = keyPath(configKey);
+ if (pathParts.length === 0) return config || {};
+
+ const root =
+  config && typeof config === "object" && !Array.isArray(config)
+   ? { ...config }
+   : {};
+ let cursor = root;
+
+ for (let index = 0; index < pathParts.length - 1; index += 1) {
+  const part = pathParts[index];
+  const existing = cursor[part];
+  cursor[part] =
+   existing && typeof existing === "object" && !Array.isArray(existing)
+    ? { ...existing }
+    : {};
+  cursor = cursor[part];
+ }
+ cursor[pathParts[pathParts.length - 1]] = section;
+ return root;
 }
 
 export function mergeServerEntry(
-  existing,
-  configKey,
-  serverName,
-  entry,
-  { enforceAuthMode = false } = {},
+ existing,
+ configKey,
+ serverName,
+ entry,
+ { enforceAuthMode = false } = {},
 ) {
-  const section = readConfigSection(existing, configKey);
-
-  if (serverName in section) {
-    // `enforceAuthMode` is opt-in and signals that the caller holds explicit
-    // auth intent (`--oauth` or `--api-key ...` on the command line). Only
-    // then do we reclassify on auth-mode mismatch and rewrite: the caller
-    // explicitly wants the Authorization header added or removed. Without
-    // that signal, setup is in the idempotent "re-run with no auth flags"
-    // mode and must preserve the existing entry byte-for-byte — otherwise
-    // a benign rerun would wipe the minted bearer key, because the ambient
-    // rebuild path constructs a headerless entry (apiKey omitted when the
-    // CLI did not resolve a new key).
-    if (
-      !enforceAuthMode ||
-      readEntryAuthMode(section[serverName]) === readEntryAuthMode(entry)
-    ) {
-      return { config: existing, alreadyExists: true };
-    }
+ const section = readConfigSection(existing, configKey);
+
+ if (serverName in section) {
+  // `enforceAuthMode` is opt-in and signals that the caller holds explicit
+  // auth intent (`--oauth` or `--api-key ...` on the command line). Only
+  // then do we reclassify on auth-mode mismatch and rewrite: the caller
+  // explicitly wants the Authorization header added or removed. Without
+  // that signal, setup is in the idempotent "re-run with no auth flags"
+  // mode and must preserve the existing entry byte-for-byte — otherwise
+  // a benign rerun would wipe the minted bearer key, because the ambient
+  // rebuild path constructs a headerless entry (apiKey omitted when the
+  // CLI did not resolve a new key).
+  if (
+   !enforceAuthMode ||
+   readEntryAuthMode(section[serverName]) === readEntryAuthMode(entry)
+  ) {
+   return { config: existing, alreadyExists: true };
   }
-
-  return {
-    config: writeConfigSection(existing, configKey, {
-      ...section,
-      [serverName]: entry,
-    }),
-    alreadyExists: false,
-  };
+ }
+
+ return {
+  config: writeConfigSection(existing, configKey, {
+   ...section,
+   [serverName]: entry,
+  }),
+  alreadyExists: false,
+ };
 }
 
 export function removeJsonServerEntry({ config, configKey, serverName }) {
-  const section = { ...readConfigSection(config, configKey) };
+ const section = { ...readConfigSection(config, configKey) };
 
-  if (!(serverName in section)) {
-    return { config: config || {}, changed: false };
-  }
+ if (!(serverName in section)) {
+  return { config: config || {}, changed: false };
+ }
 
-  delete section[serverName];
-  return {
-    config: writeConfigSection(config, configKey, section),
-    changed: true,
-  };
+ delete section[serverName];
+ return {
+  config: writeConfigSection(config, configKey, section),
+  changed: true,
+ };
 }
 
-export async function readTomlServerExists(filePath, serverName) {
-  try {
-    const raw = await readFile(filePath, "utf8");
-    return raw.includes(`[mcp_servers.${serverName}]`);
-  } catch {
-    return false;
-  }
-}
 
 export async function readTomlServerEntry(filePath, serverName) {
-  let raw = "";
-  try {
-    raw = await readFile(filePath, "utf8");
-  } catch {
-    return { exists: false, url: null, authMode: "oauth" };
+ let raw = "";
+ try {
+  raw = await readFile(filePath, "utf8");
+ } catch {
+  return { exists: false, url: null, authMode: "oauth" };
+ }
+
+ let inTargetSection = false;
+ let inHeadersSection = false;
+ let exists = false;
+ let url = null;
+ let hasAuthorizationHeader = false;
+
+ for (const { line, inString, sectionPath: sectionName } of scanTomlLines(raw)) {
+  if (inString) continue;
+  const trimmed = line.trim();
+
+  if (sectionName) {
+   const isTargetServer = sectionName[0] === "mcp_servers" && sectionName[1] === serverName;
+   if (isTargetServer && sectionName.length === 2) {
+    exists = true;
+    inTargetSection = true;
+    inHeadersSection = false;
+    continue;
+   }
+
+   if (isTargetServer && sectionName.length === 3 && sectionName[2] === "http_headers") {
+    // The http_headers block is a nested child of the parent
+    // `[mcp_servers.<name>]` section. Its presence alone does NOT imply a
+    // usable entry exists — a partially-edited config can leave the
+    // child behind after the parent is deleted, and treating the orphan
+    // as "exists" would make appendTomlServer short-circuit and refuse
+    // to recreate the missing parent block on the next setup rerun. Only
+    // the parent header toggles `exists`; here we just capture the
+    // headers subsection for auth-mode detection.
+    inTargetSection = false;
+    inHeadersSection = true;
+    continue;
+   }
+
+   // Never break out of the scan loop: TOML permits declaring tables in
+   // any order, so `[mcp_servers.<name>.http_headers]` is free to appear
+   // after an unrelated intermediate table. Breaking at the first
+   // non-target sibling would miss the headers subsection in that
+   // layout, causing auth-mode misclassification (oauth when the entry
+   // actually carries a Bearer header) and silently defeating the
+   // enforceAuthMode contract on `--oauth` reruns.
+   inTargetSection = false;
+   inHeadersSection = false;
+   continue;
   }
 
-  const normalized = normalizeLineEndings(raw);
-  const lines = normalized.split("\n");
-  const targetSection = `mcp_servers.${serverName}`;
-  const headersSection = `${targetSection}.http_headers`;
-  let inTargetSection = false;
-  let inHeadersSection = false;
-  let exists = false;
-  let url = null;
-  let hasAuthorizationHeader = false;
-
-  for (const line of lines) {
-    const trimmed = line.trim();
-    const sectionName = parseTomlSectionName(trimmed);
-
-    if (sectionName) {
-      if (sectionName === targetSection) {
-        exists = true;
-        inTargetSection = true;
-        inHeadersSection = false;
-        continue;
-      }
-
-      if (sectionName === headersSection) {
-        // The http_headers block is a nested child of the parent
-        // `[mcp_servers.<name>]` section. Its presence alone does NOT imply a
-        // usable entry exists — a partially-edited config can leave the
-        // child behind after the parent is deleted, and treating the orphan
-        // as "exists" would make appendTomlServer short-circuit and refuse
-        // to recreate the missing parent block on the next setup rerun. Only
-        // the parent header toggles `exists`; here we just capture the
-        // headers subsection for auth-mode detection.
-        inTargetSection = false;
-        inHeadersSection = true;
-        continue;
-      }
-
-      // Never break out of the scan loop: TOML permits declaring tables in
-      // any order, so `[mcp_servers.<name>.http_headers]` is free to appear
-      // after an unrelated intermediate table. Breaking at the first
-      // non-target sibling would miss the headers subsection in that
-      // layout, causing auth-mode misclassification (oauth when the entry
-      // actually carries a Bearer header) and silently defeating the
-      // enforceAuthMode contract on `--oauth` reruns.
-      inTargetSection = false;
-      inHeadersSection = false;
-      continue;
-    }
-
-    if (inTargetSection) {
-      const withoutComment = stripTomlInlineComment(trimmed);
-      const urlMatch = withoutComment.match(/^url\s*=\s*(.+)$/);
-      if (urlMatch) {
-        url = parseTomlStringValue(urlMatch[1]);
-      }
-    }
-
-    if (inHeadersSection) {
-      const withoutComment = stripTomlInlineComment(trimmed);
-      if (/^Authorization\s*=\s*/.test(withoutComment)) {
-        hasAuthorizationHeader = true;
-      }
-    }
+  if (inTargetSection) {
+   const withoutComment = stripTomlInlineComment(trimmed);
+   const urlMatch = withoutComment.match(/^url\s*=\s*(.+)$/);
+   if (urlMatch) {
+    url = parseTomlStringValue(urlMatch[1]);
+   }
   }
 
-  return {
-    exists,
-    url,
-    authMode: hasAuthorizationHeader ? "api-key" : "oauth",
-  };
-}
-
-export function buildTomlServerBlock(serverName, entry) {
-  const lines = [`[mcp_servers.${serverName}]`];
-  const headers =
-    entry && typeof entry.headers === "object" && entry.headers !== null
-      ? entry.headers
-      : null;
-
-  for (const [key, value] of Object.entries(entry || {})) {
-    if (key === "headers") continue;
-    lines.push(`${key} = ${JSON.stringify(value)}`);
+  if (inHeadersSection) {
+   const withoutComment = stripTomlInlineComment(trimmed);
+   if (/^Authorization\s*=\s*/.test(withoutComment)) {
+    hasAuthorizationHeader = true;
+   }
   }
+ }
 
-  if (headers && Object.keys(headers).length > 0) {
-    lines.push("");
-    lines.push(`[mcp_servers.${serverName}.http_headers]`);
-    for (const [headerKey, headerValue] of Object.entries(headers)) {
-      lines.push(`${headerKey} = ${JSON.stringify(String(headerValue))}`);
-    }
-  }
+ return {
+  exists,
+  url,
+  authMode: hasAuthorizationHeader ? "api-key" : "oauth",
+ };
+}
 
-  return `${lines.join("\n")}\n`;
+export function buildTomlServerBlock(serverName, entry) {
+ const { headers, ...properties } = entry || {};
+ if (headers && typeof headers === "object" && Object.keys(headers).length > 0) {
+  properties.http_headers = Object.fromEntries(
+   Object.entries(headers).map(([key, value]) => [key, String(value)]),
+  );
+ }
+ return `${stringifyToml({ mcp_servers: { [serverName]: properties } }).trimEnd()}\n`;
 }
 
 export async function appendTomlServer(
-  filePath,
-  serverName,
-  entry,
-  { enforceAuthMode = false } = {},
+ filePath,
+ serverName,
+ entry,
+ { enforceAuthMode = false, privateConfig = false, replaceExisting = false } = {},
 ) {
-  const existingEntry = await readTomlServerEntry(filePath, serverName);
-  const newAuthMode = readEntryAuthMode(entry);
-
-  if (existingEntry.exists) {
-    // Mirror `mergeServerEntry`'s `enforceAuthMode` contract: preserve the
-    // existing block on passive reruns, and only reconcile the Authorization
-    // header when the caller explicitly toggled auth mode via `--oauth` or
-    // `--api-key`.
-    if (!enforceAuthMode || existingEntry.authMode === newAuthMode) {
-      await secureFileMode(filePath);
-      return { alreadyExists: true };
-    }
-  }
-
-  let existing = "";
+ if (privateConfig) await preparePrivateConfigPath(filePath);
+ let existing = "";
+ try {
+  existing = await readFile(filePath, "utf8");
+ } catch (error) {
+  if (error?.code !== "ENOENT") throw error;
+ }
+ if (privateConfig) {
+  let current;
   try {
-    existing = await readFile(filePath, "utf8");
+   current = parseToml(existing).mcp_servers?.[serverName];
   } catch {
-    existing = "";
+   throw new Error("Private credential configuration contains invalid TOML.");
   }
-
-  // Always strip before appending on the write path. Two cases motivate an
-  // unconditional strip:
-  //   1. Auth-mode toggle (api-key ↔ oauth) with the parent section present:
-  //      without this, the prior block stays and we'd produce duplicate
-  //      `[mcp_servers.<name>]` sections.
-  //   2. Partially-edited config with an orphan
-  //      `[mcp_servers.<name>.http_headers]` subsection but no parent: the
-  //      orphan would otherwise coexist with the freshly-appended parent,
-  //      carrying stale Authorization headers into the rewritten entry.
-  // `stripCodexTomlServerBlock` is a no-op when neither the parent nor any
-  // child is present (returns `removed: false`), so it is safe to call
-  // unconditionally on the append path.
-  const { stripped } = stripCodexTomlServerBlock({
-    tomlText: existing,
-    serverName,
-  });
-  existing = stripped;
-
-  const block = buildTomlServerBlock(serverName, entry);
-  const separator =
-    existing.length > 0 && !existing.endsWith("\n")
-      ? "\n\n"
-      : existing.length > 0
-        ? "\n"
-        : "";
-  await writeSecureFile(filePath, `${existing}${separator}${block}`);
-  return { alreadyExists: false };
+  if (current) {
+   if (current.url === entry.url &&
+    current.http_headers?.Authorization === entry.headers?.Authorization) {
+    return { alreadyExists: true };
+   }
+   if (!replaceExisting) {
+    throw new Error("A different Flywheel Codex entry exists; reconcile it or explicitly use --force. Revoke the unused issued key before retrying.");
+   }
+  }
+ }
+ const existingEntry = privateConfig
+  ? { exists: false }
+  : await readTomlServerEntry(filePath, serverName);
+ const newAuthMode = readEntryAuthMode(entry);
+
+ if (existingEntry.exists) {
+  // Mirror `mergeServerEntry`'s `enforceAuthMode` contract: preserve the
+  // existing block on passive reruns, and only reconcile the Authorization
+  // header when the caller explicitly toggled auth mode via `--oauth` or
+  // `--api-key`.
+  if (!enforceAuthMode || existingEntry.authMode === newAuthMode) {
+   await secureFileMode(filePath);
+   return { alreadyExists: true };
+  }
+ }
+
+
+ // Always strip before appending on the write path. Two cases motivate an
+ // unconditional strip:
+ //   1. Auth-mode toggle (api-key ↔ oauth) with the parent section present:
+ //      without this, the prior block stays and we'd produce duplicate
+ //      `[mcp_servers.<name>]` sections.
+ //   2. Partially-edited config with an orphan
+ //      `[mcp_servers.<name>.http_headers]` subsection but no parent: the
+ //      orphan would otherwise coexist with the freshly-appended parent,
+ //      carrying stale Authorization headers into the rewritten entry.
+ // `stripCodexTomlServerBlock` is a no-op when neither the parent nor any
+ // child is present (returns `removed: false`), so it is safe to call
+ // unconditionally on the append path.
+ const { stripped } = stripCodexTomlServerBlock({
+  tomlText: existing,
+  serverName,
+ });
+ existing = stripped;
+
+ const block = buildTomlServerBlock(serverName, entry);
+ const separator =
+  existing.length > 0 && !existing.endsWith("\n")
+   ? "\n\n"
+   : existing.length > 0
+    ? "\n"
+    : "";
+ await writeSecureFile(filePath, `${existing}${separator}${block}`, undefined, undefined, {
+  atomic: privateConfig,
+ });
+ return { alreadyExists: false };
 }
 
 function stripCodexTomlServerBlock({ tomlText, serverName }) {
-  const normalized = normalizeLineEndings(tomlText || "");
-  const lines = normalized.split("\n");
-  const output = [];
-  let skipping = false;
-  let removed = false;
-
-  for (const line of lines) {
-    const trimmed = line.trim();
-    const sectionName = parseTomlSectionName(trimmed);
-
-    if (sectionName) {
-      const isTargetSection =
-        sectionName === `mcp_servers.${serverName}` ||
-        sectionName.startsWith(`mcp_servers.${serverName}.`);
-      if (isTargetSection) {
-        skipping = true;
-        removed = true;
-        continue;
-      }
-      if (skipping) {
-        skipping = false;
-      }
-    }
-
-    if (!skipping) {
-      output.push(line);
-    }
+ const output = [];
+ let skipping = false;
+ let removed = false;
+
+ for (const { line, sectionPath: sectionName } of scanTomlLines(tomlText || "")) {
+
+  if (sectionName) {
+   const isTargetSection = sectionName[0] === "mcp_servers" && sectionName[1] === serverName;
+   if (isTargetSection) {
+    skipping = true;
+    removed = true;
+    continue;
+   }
+   if (skipping) {
+    skipping = false;
+   }
   }
 
-  // Lossless when nothing matched: callers invoke this on the append path
-  // unconditionally, and the compaction below (blank-line collapsing +
-  // trimEnd + trailing newline) would otherwise mutate unrelated TOML —
-  // most notably the blank lines inside multiline `"""..."""` values and
-  // any trailing whitespace a user deliberately kept.
-  if (!removed) {
-    return { stripped: tomlText || "", removed: false };
+  if (!skipping) {
+   output.push(line);
   }
+ }
 
-  let stripped = output.join("\n");
-  stripped = stripped.replace(/\n{3,}/g, "\n\n").trimEnd();
-  if (stripped.length > 0) stripped += "\n";
-  return { stripped, removed };
+ if (!removed) {
+  return { stripped: tomlText || "", removed: false };
+ }
+
+ return { stripped: output.join("\n"), removed };
 }
 
 export async function removeCodexTomlServer({ filePath, serverName }) {
-  let existing = "";
-  try {
-    existing = await readFile(filePath, "utf8");
-  } catch {
-    return { changed: false };
-  }
-
-  const { stripped, removed } = stripCodexTomlServerBlock({
-    tomlText: existing,
-    serverName,
-  });
-  if (!removed) return { changed: false };
+ let existing = "";
+ try {
+  existing = await readFile(filePath, "utf8");
+ } catch {
+  return { changed: false };
+ }
+
+ const { stripped, removed } = stripCodexTomlServerBlock({
+  tomlText: existing,
+  serverName,
+ });
+ if (!removed) return { changed: false };
 
-  await writeSecureFile(filePath, stripped);
-  return { changed: true };
+ await writeSecureFile(filePath, stripped);
+ return { changed: true };
 }