@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.4

package/src/adapters/pi/index.js

@@ -0,0 +1,279 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+// Pi adapter — a marker-merged instruction file plus copy-tree materialisation, the same shape
+// Claude/Codex/Gemini already use for their own skills trees.
+//
+// Skills materialise into Pi's own directories (`~/.pi/agent/skills` global, `.pi/skills` project)
+// via the shared copy-tree engine, rather than pointing Pi's settings.json at DoFlow's already
+// -installed `~/.claude/skills` tree. Whether Pi discovers that directory unaided, or needs a
+// `settings.json` entry naming it, is untested here — that is task B.3's job, not this adapter's;
+// this adapter deliberately leaves settings.json untouched.
+//
+// MCP servers are merged per server into Pi's mcp.json (.pi/mcp.json project; ~/.pi/agent/mcp.json
+// or $PI_CODING_AGENT_DIR/mcp.json user) by ./mcp.ts; Pi reads it through its built-in MCP from
+// 0.99.0. Hooks are absent — Pi lifecycle handlers are TypeScript modules registered via pi.on(),
+// executing with full system permissions, which is a different trust model from the shell scripts
+// DoFlow ships.
+//
+// Evidence: https://pi.dev/docs/latest/settings, https://pi.dev/docs/latest/skills,
+// https://pi.dev/docs/latest/quickstart, https://pi.dev/docs/latest/extensions,
+// https://pi.dev/docs/latest/mcp
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { MARKER_START, MARKER_END } = require('../../helper/marker-merge.js');
+const { planTree, applyTree, removeTree, verifyTree, copyTreeAssets, copyTreeDestDir, sharedTreeDestDir, ledgerFileResources, ledgerSiblingFingerprints, siblingReplacedNotices, fingerprint, sourceDirFor } = require('../copy-tree.js');
+const { declaredHarnessPaths, resolveHarnessPaths } = require('../../helper/harness-paths.js');
+const { mcpRows, discoverPiMcp, ownedPiMcpIds, planPiMcp, applyPiMcp, verifyPiMcp } = require('./mcp.js');
+
+const HARNESS = 'pi';
+const AGENT_DIR_NOTICE = 'PI_CODING_AGENT_DIR is set: Pi reads its whole agent dir from it, but DoFlow moves only mcp.json there; skills and AGENTS.md stay in ~/.pi/agent.';
+
+// Native path facts live in core/registry/harnesses.json under this harness's "paths" section and
+// resolve through the shared harness-paths resolver; nothing below hardcodes them.
+// createPiAdapter({ declaredPaths }) is the injection point buildAdapterRegistry() uses;
+// module-level exports delegate to a default-configured instance so direct callers keep their
+// historical shape.
+function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env = process.env } = {}) {
+  // Parity note: Pi's historical nativePaths() derived even its user-scope root from scopeRoot
+  // (the CLI passes $HOME there for -g installs), never from a separate homeDir argument — so the
+  // resolver is fed no homeDir and "root" keeps resolving exactly as before.
+  function nativePaths({ scope, scopeRoot }      = {}) {
+    const paths = resolveHarnessPaths(declaredPaths, { scope, scopeRoot });
+    // Pi's user-scope mcp.json follows $PI_CODING_AGENT_DIR when set. It is not declared in the
+    // registry because the path schema has no environment base (src/helper/harness-paths.js); only
+    // mcp moves, skills and AGENTS.md keep their declared locations.
+    if ((scope === 'user' || scope === 'global') && agentDirOverride()) paths.mcp = path.join(path.resolve(agentDirOverride()), 'mcp.json');
+    return paths;
+  }
+
+  function agentDirOverride() {
+    const agentDir = env.PI_CODING_AGENT_DIR;
+    return typeof agentDir === 'string' && agentDir.trim() !== '' ? agentDir.trim() : null;
+  }
+
+  function discover({ scope, scopeRoot, mcp = [], ledger, context = {}, fsImpl = fs }     ) {
+    const paths = nativePaths({ scope, scopeRoot });
+    const instruction = fsImpl.existsSync(paths.instruction) ? fsImpl.readFileSync(paths.instruction, 'utf8') : null;
+    const rows = mcpRows(ledger);
+    const snapshot = discoverPiMcp({ selected: mcp, rows, file: paths.mcp, fsImpl });
+    // Pi reads mcp.json only for a selection or a row; the names in it are read here regardless.
+    const file = snapshot[paths.mcp] ?? discoverPiMcp({ selected: [true], rows: [], file: paths.mcp, fsImpl })[paths.mcp];
+    const members = file?.exists && file.doc?.ok ? file.doc.servers?.members ?? [] : null;
+    const mcpConfigured = members && members.map((member     ) => member.key).sort();
+    return { paths, instruction, mcp: snapshot, mcpOwned: ownedPiMcpIds({ rows, snapshot }), mcpConfigured };
+  }
+
+  function render({ content = '' }      = {}) {
+    return `${MARKER_START}\n${String(content).trimEnd()}\n${MARKER_END}\n`;
+  }
+
+  /** Replace only the span between DoFlow's markers. An AGENTS.md with no DoFlow section is refused
+   * rather than appended to — Pi shares AGENTS.md with every other agent that reads it, so where
+   * DoFlow's content belongs is its owner's decision. Add an empty marker pair to opt in. */
+  function managedInstruction(existing     , rendered     ) {
+    if (existing === null) return { ok: true, operation: 'create', content: rendered };
+    const start = existing.indexOf(MARKER_START);
+    const end = existing.indexOf(MARKER_END);
+    if (start === -1 && end === -1) return { ok: false, conflict: 'AGENTS.md exists without a DoFlow managed section' };
+    if (start === -1 || end === -1 || end < start) return { ok: false, conflict: 'AGENTS.md has malformed DoFlow managed-section markers' };
+    const content = `${existing.slice(0, start)}${rendered}${existing.slice(end + MARKER_END.length).replace(/^\n?/, '')}`;
+    return { ok: true, operation: content === existing ? 'none' : 'merge', content };
+  }
+
+  function strippedInstruction(existing     ) {
+    if (typeof existing !== 'string') return null;
+    const start = existing.indexOf(MARKER_START);
+    const end = existing.indexOf(MARKER_END);
+    if (start === -1 || end === -1 || end < start) return null;
+    let after = end + MARKER_END.length;
+    if (existing[after] === '\n') after += 1;
+    return `${existing.slice(0, start)}${existing.slice(after)}`;
+  }
+
+  // ---- copy-tree assets (skills) ----
+
+  function planCopyTreeAssets({ assets, scope, scopeRoot, context, ledger, removing, fsImpl = fs }     ) {
+    const paths = nativePaths({ scope, scopeRoot });
+    const changes = [];
+    const conflicts = [];
+    const treeResults = [];
+    const notices = [];
+    for (const asset of copyTreeAssets(assets)) {
+      const destDir = sharedTreeDestDir(paths.root, asset.nativeDir) ?? copyTreeDestDir(paths.configDir, asset);
+      const sourceDir = sourceDirFor(asset, context, fsImpl, 'Pi');
+      const previousResources = ledgerFileResources(ledger?.resources, HARNESS, asset.id);
+      const result = planTree({ sourceDir, destDir, previousResources, siblingFingerprints: ledgerSiblingFingerprints(ledger?.resources, HARNESS), operation: removing ? 'remove' : 'apply', fsImpl, layout: asset.layout, keepModified: !removing,
+        // Forwarded so the CLI's --force reaches planTree's conflict check; omitting it let
+        // planTree's own `force = false` default stand in silently. Gated on `!removing` for the
+        // reason codex/index.ts states in full: force heals drift on apply, but a hand-edited file
+        // is never deleted on removal, forced or not.
+        force: !removing && context?.force === true, });
+      treeResults.push(result);
+      conflicts.push(...result.conflicts.map((reason     ) => `${asset.id}: ${reason}`));
+      // A hand-edited file at a path DoFlow no longer writes is the user's: it stays, only its
+      // ownership row is released.
+      notices.push(...result.kept.map((item     ) => `kept hand-edited ${path.relative(paths.root, item.target)}; DoFlow no longer manages it`));
+      for (const change of result.changes) {
+        changes.push({
+          assetId: asset.id, target: change.target, source: change.source, operation: change.operation,
+          ownershipIdentity: `doflow:pi:copy-tree:${asset.id}:${change.relPath}`,
+          kind: 'copy-tree-file', identity: change.relPath,
+          afterFingerprint: change.fingerprint, fingerprint: change.fingerprint, sourceVersion: 'registry-v1',
+          ...(change.kept ? { retained: true, retainedFor: [] } : {}),
+          projection: { renderer: 'copy-tree' },
+        });
+      }
+    }
+    return { changes, conflicts, notices: [...siblingReplacedNotices(treeResults), ...notices] };
+  }
+
+  function applyCopyTreeAssets(changes     , { fsImpl = fs }      = {}) {
+    const treeChanges = changes.filter((change     ) => change.projection?.renderer === 'copy-tree' && change.operation !== 'remove')
+      .map((change     ) => ({ relPath: change.identity, target: change.target, source: change.source, operation: change.operation, fingerprint: change.fingerprint }));
+    return applyTree({ changes: treeChanges, fsImpl }).applied;
+  }
+
+  function removeCopyTreeAssets(changes     , { fsImpl = fs }      = {}) {
+    const treeChanges = changes.filter((change     ) => change.kind === 'copy-tree-file' && change.operation === 'remove' && !change.retained)
+      .map((change     ) => ({ relPath: change.identity, target: change.target, operation: 'remove', fingerprint: change.fingerprint, pruneGuard: change.pruneGuard }));
+    return removeTree({ changes: treeChanges, fsImpl }).removed;
+  }
+
+  function verifyCopyTreeAssets({ assets, scope, scopeRoot, context, fsImpl = fs }     ) {
+    const paths = nativePaths({ scope, scopeRoot });
+    const statuses = [];
+    const resources = [];
+    const conflicts = [];
+    for (const asset of copyTreeAssets(assets)) {
+      const destDir = sharedTreeDestDir(paths.root, asset.nativeDir) ?? copyTreeDestDir(paths.configDir, asset);
+      const sourceDir = sourceDirFor(asset, context, fsImpl, 'Pi');
+      const result = verifyTree({ sourceDir, destDir, fsImpl, layout: asset.layout, plannedWrites: context?.plannedWrites });
+      conflicts.push(...result.conflicts.map((reason     ) => `${asset.id}: ${reason}`));
+      for (const resource of result.resources) {
+        resources.push({
+          assetId: asset.id, target: resource.target, ownershipIdentity: `doflow:pi:copy-tree:${asset.id}:${resource.relPath}`,
+          kind: 'copy-tree-file', identity: resource.relPath,
+          fingerprint: resource.fingerprint, sourceVersion: 'registry-v1',
+          projection: { renderer: 'copy-tree' },
+        });
+      }
+      statuses.push({ harness: HARNESS, assetId: asset.id, capability: asset.capability, status: result.ok ? 'managed' : 'conflict', target: destDir });
+    }
+    return { statuses, resources, conflicts };
+  }
+
+  // ---- shared adapter contract ----
+
+  function plan({ scope, scopeRoot, assets = [], mcp = [], discovery, context = {}, ledger, fsImpl = fs }     ) {
+    const found = discovery || discover({ scope, scopeRoot, mcp, ledger, context, fsImpl });
+    const changes = [];
+    const conflicts = [];
+    const removing = context.operation === 'remove';
+
+    const guidance = assets.find((asset     ) => asset.capability === 'instructions');
+    if (guidance) {
+      const rendered = render({ content: fsImpl.readFileSync(path.resolve(context.repoRoot, guidance.source), 'utf8') });
+      const outcome = removing
+        ? { ok: true, operation: 'remove', content: strippedInstruction(found.instruction) }
+        : managedInstruction(found.instruction, rendered);
+      if (!outcome.ok) conflicts.push(outcome.conflict);
+      else if (outcome.operation !== 'none' && outcome.content !== null) {
+        changes.push({ assetId: guidance.id, target: found.paths.instruction, operation: outcome.operation,
+          content: outcome.content, ownershipIdentity: `${HARNESS}:instructions:managed-section`,
+          fingerprint: fingerprint(outcome.content), harness: HARNESS, projection: { renderer: 'pi-instructions' } });
+      }
+    }
+
+    const copyTree = planCopyTreeAssets({ assets, scope, scopeRoot, context, ledger, removing, fsImpl });
+    changes.push(...copyTree.changes);
+    conflicts.push(...copyTree.conflicts);
+
+    const piMcp = planPiMcp({ selected: mcp, rows: mcpRows(ledger), file: found.paths.mcp, scope, removing, snapshot: found.mcp, assets });
+    changes.push(...piMcp.changes);
+    conflicts.push(...piMcp.conflicts);
+
+    const notices = [...copyTree.notices, ...piMcp.notices];
+    if (!removing && scope !== 'project' && agentDirOverride()) notices.push(AGENT_DIR_NOTICE);
+    return { changes, conflicts, notices, paths: found.paths };
+  }
+
+  function writeChange(change     , fsImpl     ) {
+    fsImpl.mkdirSync(path.dirname(change.target), { recursive: true });
+    fsImpl.writeFileSync(change.target, change.content, 'utf8');
+  }
+
+  function isPiMcp(change     ) { return change.projection?.renderer === 'pi-mcp'; }
+
+  function apply({ changes = [], fsImpl = fs }     ) {
+    // MCP first: its base-hash check refuses a stale plan before any other Pi file is written.
+    let applied = applyPiMcp(changes.filter(isPiMcp), { fsImpl }).applied;
+    for (const change of changes) {
+      if (change.operation === 'remove' || change.projection?.renderer === 'copy-tree' || isPiMcp(change)) continue;
+      writeChange(change, fsImpl);
+      applied += 1;
+    }
+    applied += applyCopyTreeAssets(changes, { fsImpl });
+    // An update that no longer ships a copy-tree file carries its rows as removals inside the
+    // apply batch; the lifecycle calls remove() only for `doflow remove`.
+    removeCopyTreeAssets(changes, { fsImpl });
+    return { applied };
+  }
+
+  function remove({ changes = [], fsImpl = fs }     ) {
+    let removed = applyPiMcp(changes.filter(isPiMcp), { fsImpl }).applied;
+    for (const change of changes) {
+      if (change.operation !== 'remove' || change.projection?.renderer === 'copy-tree' || isPiMcp(change)) continue;
+      if (change.content === null) continue;
+      writeChange(change, fsImpl);
+      removed += 1;
+    }
+    removed += removeCopyTreeAssets(changes, { fsImpl });
+    return { removed };
+  }
+
+  function verify({ scope, scopeRoot, assets = [], mcp = [], discovery, ledger, context = {}, fsImpl = fs }     ) {
+    const found = discover({ scope, scopeRoot, mcp, ledger, context, fsImpl });
+    const statuses = [];
+    const resources = [];
+    const conflicts = [];
+    const instructionsAssetId = assets.find((asset     ) => asset.capability === 'instructions')?.id ?? assets[0]?.id;
+
+    const hasSection = typeof found.instruction === 'string'
+      && found.instruction.includes(MARKER_START) && found.instruction.includes(MARKER_END);
+    statuses.push({ harness: HARNESS, assetId: instructionsAssetId, capability: 'instructions',
+      status: hasSection ? 'managed' : 'absent', target: found.paths.instruction,
+      ownershipIdentity: `${HARNESS}:instructions:managed-section` });
+    if (hasSection) {
+      resources.push({ assetId: instructionsAssetId, target: found.paths.instruction,
+        ownershipIdentity: `${HARNESS}:instructions:managed-section`, fingerprint: fingerprint(found.instruction),
+        sourceVersion: context.sourceVersion ?? 'unknown', projection: { renderer: 'pi-instructions' } });
+    }
+
+    const copyTree = verifyCopyTreeAssets({ assets, scope, scopeRoot, context, fsImpl });
+    statuses.push(...copyTree.statuses);
+    resources.push(...copyTree.resources);
+    conflicts.push(...copyTree.conflicts);
+
+    const piMcp = verifyPiMcp({ selected: mcp, rows: mcpRows(ledger), file: found.paths.mcp, snapshot: (discovery ?? found).mcp,
+      removing: context.operation === 'remove', fsImpl });
+    statuses.push(...piMcp.statuses);
+    resources.push(...piMcp.resources);
+    conflicts.push(...piMcp.conflicts);
+
+    return { ok: conflicts.length === 0 && !statuses.some((s) => s.status === 'invalid' || s.status === 'conflict'), resources, statuses, conflicts };
+  }
+
+  return { nativePaths, discover, render, plan, apply, remove, verify };
+}
+
+const singleton = createPiAdapter();
+
+module.exports = {
+  HARNESS, nativePaths: singleton.nativePaths, discover: singleton.discover, render: singleton.render,
+  plan: singleton.plan, apply: singleton.apply, remove: singleton.remove, verify: singleton.verify,
+  managedInstruction: (singleton       ).managedInstruction, strippedInstruction: (singleton       ).strippedInstruction,
+  createPiAdapter,
+};

package/src/adapters/pi/json-members.js

@@ -0,0 +1,185 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+// Byte-preserving member edits on a JSON object's text. Every edit replaces exactly one span of the
+// original string, so whitespace, key order, line endings and every member DoFlow does not touch
+// survive as the user wrote them; re-serialising the parsed document would rewrite all of that.
+// Pure string in, string out: no file I/O and no knowledge of who owns which member.
+
+const SKELETON = '{\n  "mcpServers": {}\n}\n';
+const WHITESPACE = ' \t\n\r';
+
+function isPlainObject(value     )          {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function skipWhitespace(text        , i        )         {
+  while (i < text.length && WHITESPACE.includes(text[i])) i += 1;
+  return i;
+}
+
+/** Index just past the string token that opens at `i`. */
+function stringEnd(text        , i        )         {
+  for (i += 1; text[i] !== '"'; i += 1) if (text[i] === '\\') i += 1;
+  return i + 1;
+}
+
+// The text has already passed JSON.parse, so the scanner only has to find spans, never validate.
+// Only the top-level object and mcpServers need member spans; every other value is skipped by
+// counting brackets, without recursion, so a deeply nested file cannot exhaust the stack.
+function valueEnd(text        , i        )         {
+  const ch = text[i];
+  if (ch === '"') return stringEnd(text, i);
+  if (ch !== '{' && ch !== '[') {
+    while (i < text.length && !`,}]${WHITESPACE}`.includes(text[i])) i += 1;
+    return i;
+  }
+  let depth = 0;
+  for (;;) {
+    const c = text[i];
+    if (c === '"') { i = stringEnd(text, i); continue; }
+    if (c === '{' || c === '[') depth += 1;
+    else if (c === '}' || c === ']') { depth -= 1; if (depth === 0) return i + 1; }
+    i += 1;
+  }
+}
+
+/** Member spans of the object opening at `open`; `nested` names the one member whose object value
+ * is scanned for its own members too. */
+function scanObject(text        , open        , nested                = null)                                                                        {
+  const members        = [];
+  let i = skipWhitespace(text, open + 1);
+  while (text[i] !== '}') {
+    const keyStart = i;
+    const keyEnd = stringEnd(text, keyStart);
+    const key = JSON.parse(text.slice(keyStart, keyEnd));
+    const valueStart = skipWhitespace(text, skipWhitespace(text, keyEnd) + 1);
+    const node = key === nested && text[valueStart] === '{' ? scanObject(text, valueStart) : null;
+    const end = node ? node.close + 1 : valueEnd(text, valueStart);
+    members.push({ key, keyStart, valueStart, valueEnd: end, value: JSON.parse(text.slice(valueStart, end)), node });
+    i = skipWhitespace(text, end);
+    if (text[i] === ',') i = skipWhitespace(text, i + 1);
+  }
+  return { open, close: i, members };
+}
+
+/** JSON.parse's message quotes the text around the error, which may be a token or a password, so
+ * only the position is reported. */
+function invalidJsonReason(text        , error     )         {
+  const match = /at position (\d+)/.exec(error.message);
+  if (!match) return 'invalid JSON';
+  const before = text.slice(0, Number(match[1]));
+  const line = before.split('\n').length;
+  return `invalid JSON at line ${line} column ${before.length - before.lastIndexOf('\n')}`;
+}
+
+/** The whitespace that starts the line `at` sits on, or null when something else precedes it there. */
+function lineIndent(text        , at        )                {
+  const prefix = text.slice(text.lastIndexOf('\n', at - 1) + 1, at);
+  return /^[ \t]*$/.test(prefix) ? prefix : null;
+}
+
+/** The line ending most of the lines in `[start, end)` use, or `fallback` when the span has none:
+ * one stray CRLF in an LF file does not turn every inserted line into CRLF. */
+function lineEnding(text        , start        , end        , fallback        )         {
+  const span = text.slice(start, end);
+  const lines = span.split('\n').length - 1;
+  if (!lines) return fallback;
+  return (span.split('\r\n').length - 1) * 2 > lines ? '\r\n' : '\n';
+}
+
+/** Attach the formatting a container's new members follow: whether it spans lines, its line ending,
+ * the indent of its members and the indent of its closing brace. An empty container takes its parent's. */
+function attachLayout(text        , node     , parent     , unit        , eol        )       {
+  const parentIndent = parent ? parent.indent : '';
+  const empty = node.members.length === 0;
+  node.multiline = text.slice(node.open, node.close).includes('\n') || (empty && Boolean(parent?.multiline));
+  node.eol = lineEnding(text, node.open, node.close, parent ? parent.eol : eol);
+  node.indent = (!empty && lineIndent(text, node.members[0].keyStart)) || parentIndent + unit;
+  node.closeIndent = parentIndent;
+}
+
+function duplicateKey(node     )                {
+  const seen = new Set        ();
+  for (const member of node.members) {
+    if (seen.has(member.key)) return member.key;
+    seen.add(member.key);
+  }
+  return null;
+}
+
+function readDocument(text        )      {
+  let parsed;
+  try { parsed = JSON.parse(text); } catch (error     ) { return { ok: false, reason: invalidJsonReason(text, error) }; }
+  if (!isPlainObject(parsed)) return { ok: false, reason: 'top level is not an object' };
+  if (Object.prototype.hasOwnProperty.call(parsed, 'mcpServers') && !isPlainObject(parsed.mcpServers)) {
+    return { ok: false, reason: 'mcpServers is not an object' };
+  }
+  let root;
+  try { root = scanObject(text, skipWhitespace(text, 0), 'mcpServers'); } catch { return { ok: false, reason: 'the file could not be scanned' }; }
+  const duplicateTop = duplicateKey(root);
+  if (duplicateTop !== null) return { ok: false, reason: `duplicate key '${duplicateTop}'` };
+  const servers = root.members.find((member     ) => member.key === 'mcpServers')?.node ?? null;
+  const duplicateServer = servers ? duplicateKey(servers) : null;
+  if (duplicateServer !== null) return { ok: false, reason: `duplicate key '${duplicateServer}'` };
+
+  const eol = lineEnding(text, 0, text.length, '\n');
+  const spansLines = text.slice(root.open, root.close).includes('\n');
+  const unit = (spansLines && root.members.length && lineIndent(text, root.members[0].keyStart)) || '  ';
+  attachLayout(text, root, null, unit, eol);
+  if (servers) attachLayout(text, servers, root, unit, eol);
+  return { ok: true, root, servers, eol, unit };
+}
+
+function renderValue(value     , container     , layout     )         {
+  if (!container.multiline) return JSON.stringify(value);
+  return JSON.stringify(value, null, layout.unit).split('\n').join(container.eol + container.indent);
+}
+
+function renderMember(key        , value     , container     , layout     )         {
+  return `${JSON.stringify(key)}: ${renderValue(value, container, layout)}`;
+}
+
+function splice(text        , start        , end        , inserted        )         {
+  return text.slice(0, start) + inserted + text.slice(end);
+}
+
+/** `layout` is the readDocument result the container or member came from. */
+function insertMember(text        , container     , key        , value     , layout     )         {
+  const member = renderMember(key, value, container, layout);
+  const last = container.members[container.members.length - 1];
+  if (last) {
+    const inserted = container.multiline ? `,${container.eol}${container.indent}${member}` : `, ${member}`;
+    return splice(text, last.valueEnd, last.valueEnd, inserted);
+  }
+  const inserted = container.multiline
+    ? `${container.eol}${container.indent}${member}${container.eol}${container.closeIndent}`
+    : member;
+  return splice(text, container.open + 1, container.close, inserted);
+}
+
+function replaceValue(text        , member     , value     , layout     )         {
+  const container = layout.servers?.members.includes(member) ? layout.servers : layout.root;
+  return splice(text, member.valueStart, member.valueEnd, renderValue(value, container, layout));
+}
+
+function removeMember(text        , container     , member     )         {
+  const index = container.members.indexOf(member);
+  if (index === -1) throw new Error(`member '${member.key}' is not in this container`);
+  if (container.members.length === 1) return splice(text, container.open + 1, container.close, '');
+  if (index < container.members.length - 1) return splice(text, member.keyStart, container.members[index + 1].keyStart, '');
+  return splice(text, container.members[index - 1].valueEnd, member.valueEnd, '');
+}
+
+/** Set the text between an empty container's braces, which a removal of its only member drops. */
+function replaceInner(text        , container     , inner        )         {
+  if (container.members.length) throw new Error('only an empty container\'s inner text can be replaced');
+  return splice(text, container.open + 1, container.close, inner);
+}
+
+function renderNewDocument(entries     )         {
+  return `${JSON.stringify({ mcpServers: Object.fromEntries(entries) }, null, 2)}\n`;
+}
+
+module.exports = { SKELETON, readDocument, insertMember, replaceValue, removeMember, replaceInner, renderNewDocument };