deepseek-web-retrieval 0.2.0 → 0.3.0

package/src/installer/detect.ts

@@ -0,0 +1,85 @@
+import { existsSync, readFileSync } from "node:fs"
+import { removeBlock } from "./formats/rules"
+import { isPlainObject } from "./formats/value"
+import type { HostName } from "./types"
+
+/** Shared plan error: both capabilities off leaves nothing to install. */
+export const BOTH_CAPABILITIES_OFF = "Both capabilities are off; nothing would be installed."
+
+/**
+ * Shared Forced-tier cost warning; the README's "Privacy and cost" section carries
+ * the detail, so every host planner points at the same anchor.
+ */
+export const FORCED_COST_NOTE =
+  "Forced routing is deterministic, and Search and Fetch are billed per successful request — " +
+  'see the README\'s "Privacy and cost" section before applying.'
+
+/** Shared note when a previous deepseek entry is being replaced. */
+export function replacingExistingEntryNote(path: string): string {
+  return `An existing ${path} entry is being replaced; its previous form is recorded for uninstall.`
+}
+
+/** Shared note for third-party servers left registered. */
+export function othersStayRegisteredNote(others: readonly string[]): string {
+  return `Other MCP servers stay registered (${others.join(", ")}); routing to DeepSeek is not exclusive while they offer web tools.`
+}
+
+const WEB_TOOL_HINT =
+  /(web[_ -]?(search|fetch)|search|fetch|browse|scrape|crawl|tavily|brave|exa|perplexity|firecrawl|jina|serp|duckduckgo|reader)/i
+
+/**
+ * Heuristic web-capability test for a registered third-party MCP server, matching
+ * the server's name plus its command/args/url. A false positive only costs a plan
+ * note or an exclusion the user sees before --apply; a miss stays covered by the
+ * "not exclusive while they offer web tools" note.
+ */
+export function looksWebCapable(name: string, entry: unknown): boolean {
+  if (WEB_TOOL_HINT.test(name)) return true
+  if (!isPlainObject(entry)) return false
+  const command = typeof entry.command === "string" ? entry.command : ""
+  const url = typeof entry.url === "string" ? entry.url : ""
+  const args = Array.isArray(entry.args) ? entry.args.filter((arg): arg is string => typeof arg === "string").join(" ") : ""
+  return WEB_TOOL_HINT.test(`${command} ${args} ${url}`)
+}
+
+const STEERING_HINT =
+  /(web[_ ]?(search|fetch)|websearch|webfetch|tavily|exa|brave|perplexity|firecrawl|jina|serp|duckduckgo|google|bing)/i
+
+/**
+ * Detect-phase scan of the rules file the plan would write to: lines steering the
+ * model toward another web tool. The installer's own marked block is excluded, and
+ * deepseek mentions are ours to make, so both are ignored.
+ */
+export function findCompetitorSteering(host: HostName, file: string): string[] {
+  if (!existsSync(file)) return []
+  let text: string
+  try {
+    text = readFileSync(file, "utf8")
+  } catch {
+    return []
+  }
+  return removeBlock(host, text)
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0 && STEERING_HINT.test(line) && !line.includes("deepseek"))
+    .slice(0, 2)
+}
+
+/** Shared note for steering the detect phase found; conflicts are surfaced, not resolved. */
+export function competitorSteeringNote(file: string, lines: readonly string[]): string {
+  const quoted = lines.map((line) => `"${line}"`).join(", ")
+  return `Existing rules in ${file} steer toward other web tools (${quoted}); the plan surfaces this conflict — it does not resolve it.`
+}
+
+/** Splits other registered servers into web-capable competitors and bystanders. */
+export function splitCompetitors(
+  servers: Record<string, unknown>,
+): { readonly competitors: readonly string[]; readonly bystanders: readonly string[] } {
+  const competitors: string[] = []
+  const bystanders: string[] = []
+  for (const [name, entry] of Object.entries(servers)) {
+    if (name === "deepseek") continue
+    ;(looksWebCapable(name, entry) ? competitors : bystanders).push(name)
+  }
+  return { competitors, bystanders }
+}

package/src/installer/formats/index.ts

@@ -0,0 +1,58 @@
+import { mkdirSync, writeFileSync } from "node:fs"
+import { dirname } from "node:path"
+import type { ConfigOp, FileEdit, HostName, RecordedFile, RecordedOp } from "../types"
+import { jsonCodec } from "./json"
+import { rulesCodec } from "./rules"
+import { tomlCodec } from "./toml"
+
+export type ConfigFormat = FileEdit["format"]
+
+/** A config file as the codec read it: parsed, or carrying the parse error. */
+export interface LoadedConfig {
+  readonly exists: boolean
+  readonly text: string
+  readonly value: Record<string, unknown>
+  /** True when serializing the parsed value would drop comments (TOML only; JSON edits preserve them). */
+  readonly lossy: boolean
+  readonly parseError?: string
+}
+
+/** What applying one edit produced, beyond the new text: everything undo needs. */
+export interface AppliedText {
+  readonly text: string
+  readonly recorded: readonly RecordedOp[]
+  readonly createdParents: readonly (readonly string[])[]
+}
+
+/** What reverting one recorded file produced: the text plus notes about skipped work. */
+export interface RevertedText {
+  readonly text: string
+  readonly notes: readonly string[]
+}
+
+/**
+ * One codec per config format, behind a single registry: load parses, apply edits,
+ * verify checks postconditions (per op for json/toml, block presence for rules),
+ * revert reverses a recorded file, and isEffectivelyEmpty gates whole-file deletion.
+ */
+export interface FormatCodec {
+  readonly format: ConfigFormat
+  load(file: string): LoadedConfig
+  apply(text: string, edit: FileEdit): AppliedText
+  verify(text: string, edit: FileEdit, op?: ConfigOp): boolean
+  revert(text: string, recorded: RecordedFile): RevertedText
+  isEffectivelyEmpty(text: string): boolean
+}
+
+/** Shared write step: every codec consumer writes config files through this. */
+export function writeConfig(file: string, serialized: string): void {
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, serialized)
+}
+
+/** The one entry point to a format's codec; only the rules codec cares about the host. */
+export function codecFor(format: ConfigFormat, host: HostName): FormatCodec {
+  if (format === "json") return jsonCodec
+  if (format === "toml") return tomlCodec
+  return rulesCodec(host)
+}

package/src/installer/formats/json.ts

@@ -0,0 +1,151 @@
+import { existsSync, readFileSync } from "node:fs"
+import { applyEdits, modify, parse, type JSONPath } from "jsonc-parser/lib/esm/main.js"
+import { parseJsonc } from "../../core/jsonc"
+import type { ConfigOp, RecordedOp } from "../types"
+import type { AppliedText, FormatCodec, LoadedConfig } from "./index"
+import { appendEntries, deepEqual, isPlainObject, valueAt } from "./value"
+
+const JSON_FORMATTING = { insertSpaces: true, tabSize: 2, insertFinalNewline: false } as const
+
+/** Reads a JSONC config file; a missing file starts empty, an unparsable one carries the error. */
+function loadJson(file: string): LoadedConfig {
+  if (!existsSync(file)) return { exists: false, text: "", value: {}, lossy: false }
+  const text = readFileSync(file, "utf8")
+  try {
+    return { exists: true, text, value: parseJsonc(text) as Record<string, unknown>, lossy: false }
+  } catch (error) {
+    const parseError = error instanceof Error ? error.message : String(error)
+    return { exists: true, text, value: {}, lossy: false, parseError }
+  }
+}
+
+/** Reads the value at a dotted path from JSON text, or undefined when absent. */
+function jsonGet(text: string, path: readonly string[]): unknown {
+  const root = parse(text, undefined, { allowTrailingComma: true }) as Record<string, unknown>
+  return valueAt(root, path)
+}
+
+export interface JsonOpsResult {
+  readonly text: string
+  readonly recorded: RecordedOp[]
+  /** Path prefixes the ops had to create; uninstall removes them when left empty. */
+  readonly createdParents: readonly (readonly string[])[]
+}
+
+/**
+ * Applies ops to JSONC text with jsonc-parser's comment-preserving edits.
+ * Ops are idempotent: `set` writes the value, `append-array` skips deep-equal entries.
+ * Each op is recorded with its previous value (or the entries actually appended)
+ * for surgical undo.
+ */
+export function applyJsonOps(text: string, ops: readonly ConfigOp[]): JsonOpsResult {
+  let current = text.trim().length > 0 ? text : "{}\n"
+  const recorded: RecordedOp[] = []
+  const createdParents: (readonly string[])[] = []
+  for (const op of ops) {
+    const path = op.path as unknown as JSONPath
+    if (op.op === "set") {
+      current = ensureParents(current, op.path, createdParents)
+      const previous = jsonGet(current, op.path)
+      current = edit(current, path, op.value)
+      recorded.push({ op: "set", path: op.path, applied: structuredClone(op.value), previous })
+      continue
+    }
+    current = ensureParents(current, op.path, createdParents)
+    const existing = jsonGet(current, op.path)
+    const { list, appended } = appendEntries(existing, op.entries ?? [], op.path)
+    if (existing === undefined) {
+      current = edit(current, path, [])
+      createdParents.push(op.path)
+    }
+    let index = list.length
+    for (const entry of appended) {
+      current = edit(current, [...path, index] as unknown as JSONPath, entry)
+      index += 1
+    }
+    recorded.push({ op: "append-array", path: op.path, applied: appended, previous: undefined })
+  }
+  return { text: current, recorded, createdParents }
+}
+
+/** Reverses recorded ops on current JSON text; returns the text plus notes about skipped work. */
+export function revertJsonOps(text: string, ops: readonly RecordedOp[], createdParents: readonly (readonly string[])[]): { text: string; notes: string[] } {
+  let current = text
+  const notes: string[] = []
+  for (const record of [...ops].reverse()) {
+    const path = record.path as unknown as JSONPath
+    if (record.op === "set") {
+      const now = jsonGet(current, record.path)
+      if (now === undefined) continue
+      if (!deepEqual(now, record.applied)) {
+        notes.push(`${record.path.join(".")}: current value differs from what the installer wrote; left untouched`)
+        continue
+      }
+      current = record.previous === undefined ? edit(current, path, void 0) : edit(current, path, record.previous)
+    } else {
+      const entries = Array.isArray(record.applied) ? record.applied : []
+      for (const entry of [...entries].reverse()) {
+        const list = jsonGet(current, record.path)
+        if (!Array.isArray(list)) continue
+        const index = list.findIndex((item) => deepEqual(item, entry))
+        if (index === -1) continue
+        current = edit(current, [...path, index] as unknown as JSONPath, void 0)
+      }
+    }
+  }
+  for (const parent of [...createdParents].reverse()) {
+    const value = jsonGet(current, parent)
+    const isEmptyObject = isPlainObject(value) && Object.keys(value).length === 0
+    const isEmptyArray = Array.isArray(value) && value.length === 0
+    if (isEmptyObject || isEmptyArray) {
+      current = edit(current, parent as unknown as JSONPath, void 0)
+    }
+  }
+  return { text: current, notes }
+}
+
+function edit(text: string, path: JSONPath, value: unknown): string {
+  return applyEdits(text, modify(text, path, value as never, { formattingOptions: JSON_FORMATTING }))
+}
+
+/** Creates missing path prefixes as objects (or arrays when the next segment is an index). */
+function ensureParents(text: string, path: readonly string[], created: (readonly string[])[]): string {
+  let current = text
+  for (let depth = 0; depth < path.length - 1; depth += 1) {
+    const prefix = path.slice(0, depth + 1)
+    const existing = jsonGet(current, prefix)
+    if (existing !== undefined && typeof existing !== "object") {
+      throw new Error(`cannot descend into ${prefix.join(".")}: it is a ${typeof existing}, not an object`)
+    }
+    if (existing !== undefined) continue
+    const nextSegmentIsIndex = Number.isInteger(Number(path[depth + 1]))
+    const placeholder = nextSegmentIsIndex ? [] : {}
+    current = edit(current, prefix as unknown as JSONPath, placeholder)
+    created.push(prefix)
+  }
+  return current
+}
+
+function jsonOpHolds(text: string, op: ConfigOp): boolean {
+  if (op.op === "set") return deepEqual(jsonGet(text, op.path), op.value)
+  const list = jsonGet(text, op.path)
+  return Array.isArray(list) && (op.entries ?? []).every((entry) => list.some((item) => deepEqual(item, entry)))
+}
+
+/** The JSON codec: comment-preserving edits on JSONC text. */
+export const jsonCodec: FormatCodec = {
+  format: "json",
+  load: loadJson,
+  apply: (text, edit): AppliedText => {
+    if (edit.format !== "json") throw new Error(`json codec cannot apply a ${edit.format} edit`)
+    const result = applyJsonOps(text, edit.ops)
+    return { text: result.text, recorded: result.recorded, createdParents: result.createdParents }
+  },
+  verify: (text, edit, op) => {
+    if (edit.format !== "json") throw new Error(`json codec cannot verify a ${edit.format} edit`)
+    const ops = op === undefined ? edit.ops : [op]
+    return ops.every((candidate) => jsonOpHolds(text, candidate))
+  },
+  revert: (text, recorded) => revertJsonOps(text, recorded.ops, recorded.createdParents ?? []),
+  isEffectivelyEmpty: (text) => text.replace(/[{}\s]/g, "").length === 0,
+}

package/src/installer/formats/rules.ts

@@ -0,0 +1,62 @@
+import { existsSync, readFileSync } from "node:fs"
+import type { HostName } from "../types"
+import type { AppliedText, FormatCodec } from "./index"
+
+/** Marked-block markers are per host, so multiple hosts can share one rules file. */
+function rulesMarkers(host: HostName): { readonly begin: string; readonly end: string } {
+  return {
+    begin: `<!-- deepseek-web-retrieval:${host}:rules:begin -->`,
+    end: `<!-- deepseek-web-retrieval:${host}:rules:end -->`,
+  }
+}
+
+/** Wraps rule lines in the host's marked block that apply upserts and uninstall remove. */
+export function buildRulesBlock(host: HostName, lines: readonly string[]): string {
+  const markers = rulesMarkers(host)
+  return [markers.begin, ...lines, markers.end].join("\n")
+}
+
+/** Replaces the host's existing marked block, or appends one; keeps surrounding text intact. */
+export function upsertBlock(host: HostName, text: string, block: string): string {
+  const without = removeBlock(host, text)
+  const trimmed = without.trimEnd()
+  return trimmed ? `${trimmed}\n\n${block}\n` : `${block}\n`
+}
+
+/** Removes the host's marked block if present; returns the text unchanged otherwise. */
+export function removeBlock(host: HostName, text: string): string {
+  const markers = rulesMarkers(host)
+  const start = text.indexOf(markers.begin)
+  if (start === -1) return text
+  const end = text.indexOf(markers.end)
+  if (end === -1) return text.slice(0, start)
+  let after = text.slice(end + markers.end.length)
+  // Drop the blank lines the upsert added around the block.
+  after = after.replace(/^\n{1,2}/, "")
+  const before = text.slice(0, start)
+  return before.endsWith("\n\n") ? `${before.slice(0, -1)}${after}` : before + after
+}
+
+export function hasBlock(host: HostName, text: string): boolean {
+  const markers = rulesMarkers(host)
+  return text.includes(markers.begin) && text.includes(markers.end)
+}
+
+/** A rules codec is per host: its markers decide which block upsert, verify, and revert touch. */
+export function rulesCodec(host: HostName): FormatCodec {
+  return {
+    format: "rules",
+    load: (file) =>
+      existsSync(file)
+        ? { exists: true, text: readFileSync(file, "utf8"), value: {}, lossy: false }
+        : { exists: false, text: "", value: {}, lossy: false },
+    apply: (text, edit): AppliedText => {
+      if (edit.format !== "rules") throw new Error(`rules codec cannot apply a ${edit.format} edit`)
+      return { text: upsertBlock(host, text, edit.block), recorded: [], createdParents: [] }
+    },
+    // Rules files are markdown: the block's presence is the only postcondition.
+    verify: (text) => hasBlock(host, text),
+    revert: (text) => ({ text: removeBlock(host, text), notes: [] }),
+    isEffectivelyEmpty: (text) => text.trim().length === 0,
+  }
+}

package/src/installer/formats/toml.ts

@@ -0,0 +1,163 @@
+import { existsSync, readFileSync } from "node:fs"
+import { parse as parseToml, stringify as stringifyTomlValue } from "smol-toml"
+import type { ConfigOp, RecordedOp } from "../types"
+import type { AppliedText, FormatCodec, LoadedConfig } from "./index"
+import { appendEntries, deepEqual, isPlainObject, removeAt, valueAt } from "./value"
+
+/** Reads a TOML config file; a missing file starts empty, an unparsable one carries the error. */
+function loadToml(file: string): LoadedConfig {
+  if (!existsSync(file)) return { exists: false, text: "", value: {}, lossy: false }
+  const text = readFileSync(file, "utf8")
+  try {
+    return { exists: true, text, value: parseToml(text) as Record<string, unknown>, lossy: hasTomlComment(text) }
+  } catch (error) {
+    const parseError = error instanceof Error ? error.message : String(error)
+    return { exists: true, text, value: {}, lossy: false, parseError }
+  }
+}
+
+/**
+ * String-aware TOML comment detection: any `#` outside basic ("") or literal ('')
+ * strings counts, including trailing comments like `key = "x" # note`.
+ */
+export function hasTomlComment(text: string): boolean {
+  let inBasic = false
+  let inLiteral = false
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i] as string
+    if (inBasic) {
+      if (ch === "\\") i += 1
+      else if (ch === '"') inBasic = false
+      continue
+    }
+    if (inLiteral) {
+      if (ch === "'") inLiteral = false
+      continue
+    }
+    if (ch === '"') inBasic = true
+    else if (ch === "'") inLiteral = true
+    else if (ch === "#") return true
+  }
+  return false
+}
+
+function serializeToml(value: Record<string, unknown>): string {
+  return `${stringifyTomlValue(value)}\n`
+}
+
+/**
+ * Applies ops to a parsed TOML value, returning the mutated value plus one record
+ * per op with the previous value for surgical undo, and the path prefixes created.
+ */
+function applyTomlOps(value: Record<string, unknown>, ops: readonly ConfigOp[]): { value: Record<string, unknown>; recorded: RecordedOp[]; createdParents: (readonly string[])[] } {
+  const target: Record<string, unknown> = structuredClone(value)
+  const recorded: RecordedOp[] = []
+  const createdParents: (readonly string[])[] = []
+  for (const op of ops) {
+    const parent = navigate(target, op.path, createdParents)
+    const key = op.path[op.path.length - 1]
+    if (op.op === "set") {
+      const previous = Object.prototype.hasOwnProperty.call(parent, key) ? parent[key] : undefined
+      parent[key] = structuredClone(op.value)
+      recorded.push({ op: "set", path: op.path, applied: structuredClone(op.value), previous })
+      continue
+    }
+    const existing = parent[key]
+    if (existing === undefined) createdParents.push(op.path)
+    const { list, appended } = appendEntries(existing, op.entries ?? [], op.path)
+    parent[key] = [...list, ...appended.map((entry) => structuredClone(entry))]
+    recorded.push({ op: "append-array", path: op.path, applied: appended, previous: undefined })
+  }
+  return { value: target, recorded, createdParents }
+}
+
+function navigate(root: Record<string, unknown>, path: readonly string[], created: (readonly string[])[]): Record<string, unknown> {
+  let node = root
+  for (let depth = 0; depth < path.length - 1; depth += 1) {
+    const key = path[depth] as string
+    const next: unknown = node[key]
+    if (next === undefined) {
+      node[key] = {}
+      created.push(path.slice(0, depth + 1))
+    } else if (!isPlainObject(next)) {
+      throw new Error(
+        `cannot descend into ${path.slice(0, depth + 1).join(".")}: it is ${Array.isArray(next) ? "an array" : `a ${typeof next}`}, not a table`,
+      )
+    }
+    node = node[key] as Record<string, unknown>
+  }
+  return node
+}
+
+/** Surgical undo on a parsed TOML object; user edits made after install win. */
+function revertTomlOps(value: Record<string, unknown>, ops: readonly RecordedOp[]): string[] {
+  const notes: string[] = []
+  for (const record of [...ops].reverse()) {
+    if (record.op === "set") {
+      const now = valueAt(value, record.path)
+      if (now === undefined) continue
+      if (!deepEqual(now, record.applied)) {
+        notes.push(`${record.path.join(".")}: current value differs from what the installer wrote; left untouched`)
+        continue
+      }
+      if (record.previous === undefined) {
+        removeAt(value, record.path)
+      } else {
+        setValueAt(value, record.path, record.previous)
+      }
+    } else {
+      const entries = Array.isArray(record.applied) ? record.applied : []
+      for (const entry of entries) {
+        const list = valueAt(value, record.path)
+        if (!Array.isArray(list)) continue
+        const index = list.findIndex((item) => deepEqual(item, entry))
+        if (index === -1) continue
+        list.splice(index, 1)
+      }
+    }
+  }
+  return notes
+}
+
+/** Removes path prefixes the installer created when they are left empty, newest first. */
+function pruneCreatedParents(value: Record<string, unknown>, parents: readonly (readonly string[])[]): void {
+  for (const parent of [...parents].reverse()) {
+    const current = valueAt(value, parent)
+    if (isPlainObject(current) && Object.keys(current).length === 0) removeAt(value, parent)
+  }
+}
+
+function setValueAt(value: Record<string, unknown>, path: readonly string[], replacement: unknown): void {
+  const parent = valueAt(value, path.slice(0, -1))
+  if (isPlainObject(parent)) parent[path[path.length - 1] as string] = replacement
+}
+
+function tomlOpHolds(text: string, op: ConfigOp): boolean {
+  const value = parseToml(text) as Record<string, unknown>
+  const current = valueAt(value, op.path)
+  if (op.op === "set") return deepEqual(current, op.value)
+  return Array.isArray(current) && (op.entries ?? []).every((entry) => current.some((item) => deepEqual(item, entry)))
+}
+
+/** The TOML codec: ops on a parsed value, serialized lossily (comments drop on rewrite). */
+export const tomlCodec: FormatCodec = {
+  format: "toml",
+  load: loadToml,
+  apply: (text, edit): AppliedText => {
+    if (edit.format !== "toml") throw new Error(`toml codec cannot apply a ${edit.format} edit`)
+    const result = applyTomlOps(parseToml(text) as Record<string, unknown>, edit.ops)
+    return { text: serializeToml(result.value), recorded: result.recorded, createdParents: result.createdParents }
+  },
+  verify: (text, edit, op) => {
+    if (edit.format !== "toml") throw new Error(`toml codec cannot verify a ${edit.format} edit`)
+    const ops = op === undefined ? edit.ops : [op]
+    return ops.every((candidate) => tomlOpHolds(text, candidate))
+  },
+  revert: (text, recorded) => {
+    const value = parseToml(text) as Record<string, unknown>
+    const notes = revertTomlOps(value, recorded.ops)
+    pruneCreatedParents(value, recorded.createdParents ?? [])
+    return { text: serializeToml(value), notes }
+  },
+  isEffectivelyEmpty: (text) => Object.keys(parseToml(text) as Record<string, unknown>).length === 0,
+}

package/src/installer/formats/value.ts

@@ -0,0 +1,57 @@
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+export function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true
+  if (a === null || b === null || typeof a !== "object" || typeof b !== "object") return false
+  const aArray = Array.isArray(a)
+  const bArray = Array.isArray(b)
+  if (aArray !== bArray) return false
+  if (aArray && bArray) {
+    const x = a as unknown[]
+    const y = b as unknown[]
+    return x.length === y.length && x.every((item, index) => deepEqual(item, y[index]))
+  }
+  const x = a as Record<string, unknown>
+  const y = b as Record<string, unknown>
+  const xKeys = Object.keys(x)
+  const yKeys = Object.keys(y)
+  return xKeys.length === yKeys.length && xKeys.every((key) => deepEqual(x[key], y[key]))
+}
+
+/** Reads the value at a dotted path from a parsed object, or undefined when absent. */
+export function valueAt(value: Record<string, unknown>, path: readonly string[]): unknown {
+  let node: unknown = value
+  for (const key of path) {
+    if (Array.isArray(node)) {
+      const index = Number(key)
+      node = Number.isInteger(index) ? node[index] : undefined
+    } else if (isPlainObject(node)) {
+      node = node[key]
+    } else {
+      return undefined
+    }
+    if (node === undefined) return undefined
+  }
+  return node
+}
+
+export function removeAt(value: Record<string, unknown>, path: readonly string[]): void {
+  const parent = valueAt(value, path.slice(0, -1))
+  if (isPlainObject(parent)) delete parent[path[path.length - 1] as string]
+}
+
+/**
+ * Shared append-array step for both config formats: rejects a non-array at the
+ * path and dedupes entries already present, so applied records list only what
+ * was actually appended.
+ */
+export function appendEntries(existing: unknown, entries: readonly unknown[], path: readonly string[]): { readonly list: readonly unknown[]; readonly appended: readonly unknown[] } {
+  if (existing !== undefined && !Array.isArray(existing)) {
+    throw new Error(`cannot append to ${path.join(".")}: it is a ${typeof existing}, not an array`)
+  }
+  const list = Array.isArray(existing) ? existing : []
+  const appended = entries.filter((entry) => !list.some((item) => deepEqual(item, entry)))
+  return { list, appended }
+}