@khoavu882/doflow 2.0.0-beta.3 → 2.0.0-beta.5

package/src/adapters/pi/{index.ts → index.js}

@@ -13,9 +13,7 @@
 //
 // 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.
+// 0.99.0. The user- and project-scope lifecycle extension is ledger-owned and resolves its shared bridge at install time.
 //
 // 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,
@@ -23,13 +21,15 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
-const { MARKER_START, MARKER_END } = require('../../helper/marker-merge.ts');
-const { planTree, applyTree, removeTree, verifyTree, copyTreeAssets, copyTreeDestDir, sharedTreeDestDir, ledgerFileResources, ledgerSiblingFingerprints, siblingReplacedNotices, fingerprint, sourceDirFor } = require('../copy-tree.ts');
-const { declaredHarnessPaths, resolveHarnessPaths } = require('../../helper/harness-paths.ts');
-const { mcpRows, discoverPiMcp, ownedPiMcpIds, planPiMcp, applyPiMcp, verifyPiMcp } = require('./mcp.ts');
+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 { planPiHooks, verifyPiHooks, removePiHooks } = require('./hooks.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.';
+const AGENT_DIR_MCP_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.';
+const AGENT_DIR_NOTICE = 'PI_CODING_AGENT_DIR is set: Pi reads its whole agent dir from it, and DoFlow moves mcp.json and the guard extension 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.
@@ -40,11 +40,11 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], 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 }: any = {}) {
+  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.
+    // registry because the path schema has no environment base (src/helper/harness-paths.js); the
+    // guard extension follows it too, while 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;
   }
@@ -54,7 +54,7 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env
     return typeof agentDir === 'string' && agentDir.trim() !== '' ? agentDir.trim() : null;
   }
 
-  function discover({ scope, scopeRoot, mcp = [], ledger, context = {}, fsImpl = fs }: any) {
+  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);
@@ -62,18 +62,18 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env
     // 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: any) => member.key).sort();
+    const mcpConfigured = members && members.map((member     ) => member.key).sort();
     return { paths, instruction, mcp: snapshot, mcpOwned: ownedPiMcpIds({ rows, snapshot }), mcpConfigured };
   }
 
-  function render({ content = '' }: any = {}) {
+  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: any, rendered: any) {
+  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);
@@ -83,7 +83,7 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env
     return { ok: true, operation: content === existing ? 'none' : 'merge', content };
   }
 
-  function strippedInstruction(existing: any) {
+  function strippedInstruction(existing     ) {
     if (typeof existing !== 'string') return null;
     const start = existing.indexOf(MARKER_START);
     const end = existing.indexOf(MARKER_END);
@@ -95,7 +95,7 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env
 
   // ---- copy-tree assets (skills) ----
 
-  function planCopyTreeAssets({ assets, scope, scopeRoot, context, ledger, removing, fsImpl = fs }: any) {
+  function planCopyTreeAssets({ assets, scope, scopeRoot, context, ledger, removing, fsImpl = fs }     ) {
     const paths = nativePaths({ scope, scopeRoot });
     const changes = [];
     const conflicts = [];
@@ -112,10 +112,10 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env
         // is never deleted on removal, forced or not.
         force: !removing && context?.force === true, });
       treeResults.push(result);
-      conflicts.push(...result.conflicts.map((reason: any) => `${asset.id}: ${reason}`));
+      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: any) => `kept hand-edited ${path.relative(paths.root, item.target)}; DoFlow no longer manages it`));
+      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,
@@ -130,19 +130,19 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env
     return { changes, conflicts, notices: [...siblingReplacedNotices(treeResults), ...notices] };
   }
 
-  function applyCopyTreeAssets(changes: any, { fsImpl = fs }: any = {}) {
-    const treeChanges = changes.filter((change: any) => change.projection?.renderer === 'copy-tree' && change.operation !== 'remove')
-      .map((change: any) => ({ relPath: change.identity, target: change.target, source: change.source, operation: change.operation, fingerprint: change.fingerprint }));
+  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: any, { fsImpl = fs }: any = {}) {
-    const treeChanges = changes.filter((change: any) => change.kind === 'copy-tree-file' && change.operation === 'remove' && !change.retained)
-      .map((change: any) => ({ relPath: change.identity, target: change.target, operation: 'remove', fingerprint: change.fingerprint, pruneGuard: change.pruneGuard }));
+  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 }: any) {
+  function verifyCopyTreeAssets({ assets, scope, scopeRoot, context, fsImpl = fs }     ) {
     const paths = nativePaths({ scope, scopeRoot });
     const statuses = [];
     const resources = [];
@@ -151,7 +151,7 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env
       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: any) => `${asset.id}: ${reason}`));
+      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}`,
@@ -167,13 +167,13 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env
 
   // ---- shared adapter contract ----
 
-  function plan({ scope, scopeRoot, assets = [], mcp = [], discovery, context = {}, ledger, fsImpl = fs }: any) {
+  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: any) => asset.capability === 'instructions');
+    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
@@ -191,23 +191,40 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env
     changes.push(...copyTree.changes);
     conflicts.push(...copyTree.conflicts);
 
+    const piHooks = planPiHooks({ scope, scopeRoot, assets, ledger, context, adopt: context?.adopt === true, env, fsImpl });
+    changes.push(...piHooks.changes);
+    conflicts.push(...piHooks.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);
+    const notices = [...copyTree.notices, ...piMcp.notices, ...piHooks.notices];
+    if (!removing && scope !== 'project' && agentDirOverride()) {
+      notices.push(assets.some((asset     ) => asset.id === 'pi.guard-extension') ? AGENT_DIR_NOTICE : AGENT_DIR_MCP_NOTICE);
+    }
     return { changes, conflicts, notices, paths: found.paths };
   }
 
-  function writeChange(change: any, fsImpl: any) {
+  /** The hook front door (IC-037): the guard extension. */
+  function planHookDoors({ scope, scopeRoot, assets = [], context = {}, ledger, fsImpl = fs }     ) {
+    const door = planPiHooks({ scope, scopeRoot, assets, ledger, context, adopt: context?.adopt === true, env, fsImpl });
+    return { changes: door.changes, conflicts: door.conflicts, notices: door.notices };
+  }
+
+  function verifyHookDoors({ scope, scopeRoot, assets = [], ledger, context = {}, fsImpl = fs }     ) {
+    const door = verifyPiHooks({ scope, scopeRoot, assets, ledger, context, adopt: context?.adopt === true, env, fsImpl });
+    return { ok: door.conflicts.length === 0 && !door.statuses.some((s     ) => s.status === 'invalid' || s.status === 'conflict'), ...door };
+  }
+
+  function writeChange(change     , fsImpl     ) {
     fsImpl.mkdirSync(path.dirname(change.target), { recursive: true });
     fsImpl.writeFileSync(change.target, change.content, 'utf8');
   }
 
-  function isPiMcp(change: any) { return change.projection?.renderer === 'pi-mcp'; }
+  function isPiMcp(change     ) { return change.projection?.renderer === 'pi-mcp'; }
 
-  function apply({ changes = [], fsImpl = fs }: any) {
+  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) {
@@ -222,24 +239,26 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env
     return { applied };
   }
 
-  function remove({ changes = [], fsImpl = fs }: any) {
+  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.projection?.renderer === 'pi-guard-extension') continue;
       if (change.content === null) continue;
       writeChange(change, fsImpl);
       removed += 1;
     }
+    removed += removePiHooks(changes, { fsImpl });
     removed += removeCopyTreeAssets(changes, { fsImpl });
     return { removed };
   }
 
-  function verify({ scope, scopeRoot, assets = [], mcp = [], discovery, ledger, context = {}, fsImpl = fs }: any) {
+  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: any) => asset.capability === 'instructions')?.id ?? assets[0]?.id;
+    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);
@@ -263,10 +282,15 @@ function createPiAdapter({ declaredPaths = declaredHarnessPaths()[HARNESS], env
     resources.push(...piMcp.resources);
     conflicts.push(...piMcp.conflicts);
 
+    const piHooks = verifyPiHooks({ scope, scopeRoot, assets, ledger, context, adopt: context?.adopt === true, env, fsImpl });
+    statuses.push(...piHooks.statuses);
+    resources.push(...piHooks.resources);
+    conflicts.push(...piHooks.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 };
+  return { nativePaths, discover, render, plan, apply, remove, verify, planHookDoors, verifyHookDoors };
 }
 
 const singleton = createPiAdapter();
@@ -274,6 +298,7 @@ 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 as any).managedInstruction, strippedInstruction: (singleton as any).strippedInstruction,
+  planHookDoors: singleton.planHookDoors, verifyHookDoors: singleton.verifyHookDoors,
+  managedInstruction: (singleton       ).managedInstruction, strippedInstruction: (singleton       ).strippedInstruction,
   createPiAdapter,
 };

package/src/adapters/pi/{json-members.ts → json-members.js}

@@ -10,17 +10,17 @@
 const SKELETON = '{\n  "mcpServers": {}\n}\n';
 const WHITESPACE = ' \t\n\r';
 
-function isPlainObject(value: any): boolean {
+function isPlainObject(value     )          {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 
-function skipWhitespace(text: string, i: number): number {
+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: string, i: number): number {
+function stringEnd(text        , i        )         {
   for (i += 1; text[i] !== '"'; i += 1) if (text[i] === '\\') i += 1;
   return i + 1;
 }
@@ -28,7 +28,7 @@ function stringEnd(text: string, i: number): number {
 // 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: string, i: number): number {
+function valueEnd(text        , i        )         {
   const ch = text[i];
   if (ch === '"') return stringEnd(text, i);
   if (ch !== '{' && ch !== '[') {
@@ -47,8 +47,8 @@ function valueEnd(text: string, i: number): number {
 
 /** 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: string, open: number, nested: string | null = null): { open: number, close: number, members: any[], [extra: string]: any } {
-  const members: any[] = [];
+function scanObject(text        , open        , nested                = null)                                                                        {
+  const members        = [];
   let i = skipWhitespace(text, open + 1);
   while (text[i] !== '}') {
     const keyStart = i;
@@ -66,7 +66,7 @@ function scanObject(text: string, open: number, nested: string | null = null): {
 
 /** 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: string, error: any): string {
+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]));
@@ -75,14 +75,14 @@ function invalidJsonReason(text: string, error: any): string {
 }
 
 /** The whitespace that starts the line `at` sits on, or null when something else precedes it there. */
-function lineIndent(text: string, at: number): string | null {
+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: string, start: number, end: number, fallback: string): string {
+function lineEnding(text        , start        , end        , fallback        )         {
   const span = text.slice(start, end);
   const lines = span.split('\n').length - 1;
   if (!lines) return fallback;
@@ -91,7 +91,7 @@ function lineEnding(text: string, start: number, end: number, fallback: string):
 
 /** 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: string, node: any, parent: any, unit: string, eol: string): void {
+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));
@@ -100,8 +100,8 @@ function attachLayout(text: string, node: any, parent: any, unit: string, eol: s
   node.closeIndent = parentIndent;
 }
 
-function duplicateKey(node: any): string | null {
-  const seen = new Set<string>();
+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);
@@ -109,9 +109,9 @@ function duplicateKey(node: any): string | null {
   return null;
 }
 
-function readDocument(text: string): any {
+function readDocument(text        )      {
   let parsed;
-  try { parsed = JSON.parse(text); } catch (error: any) { return { ok: false, reason: invalidJsonReason(text, error) }; }
+  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' };
@@ -120,7 +120,7 @@ function readDocument(text: string): any {
   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: any) => member.key === 'mcpServers')?.node ?? null;
+  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}'` };
 
@@ -132,21 +132,21 @@ function readDocument(text: string): any {
   return { ok: true, root, servers, eol, unit };
 }
 
-function renderValue(value: any, container: any, layout: any): string {
+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: string, value: any, container: any, layout: any): string {
+function renderMember(key        , value     , container     , layout     )         {
   return `${JSON.stringify(key)}: ${renderValue(value, container, layout)}`;
 }
 
-function splice(text: string, start: number, end: number, inserted: string): string {
+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: string, container: any, key: string, value: any, layout: any): string {
+function insertMember(text        , container     , key        , value     , layout     )         {
   const member = renderMember(key, value, container, layout);
   const last = container.members[container.members.length - 1];
   if (last) {
@@ -159,12 +159,12 @@ function insertMember(text: string, container: any, key: string, value: any, lay
   return splice(text, container.open + 1, container.close, inserted);
 }
 
-function replaceValue(text: string, member: any, value: any, layout: any): string {
+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: string, container: any, member: any): string {
+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, '');
@@ -173,12 +173,12 @@ function removeMember(text: string, container: any, member: any): string {
 }
 
 /** Set the text between an empty container's braces, which a removal of its only member drops. */
-function replaceInner(text: string, container: any, inner: string): string {
+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: any): string {
+function renderNewDocument(entries     )         {
   return `${JSON.stringify({ mcpServers: Object.fromEntries(entries) }, null, 2)}\n`;
 }