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

package/src/adapters/codex/agents.ts

@@ -0,0 +1,208 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+// Codex custom-agent projection. Agent contracts are independent TOML documents, so unlike
+// config.toml there is no safe key-level merge: a same-named destination is changed only when
+// the manifest proves DoFlow owns the exact bytes currently on disk.
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const { atomicWrite } = require('./config.ts');
+
+const AGENT_DIRECTORY = 'agents';
+const AGENT_KIND = 'custom-agent';
+const REQUIRED_FIELDS = ['name', 'description', 'developer_instructions'];
+const READ_ONLY_ROLES = new Set([
+  'backend-architect', 'deep-research-agent', 'devops-architect', 'frontend-architect',
+  'quality-engineer', 'requirements-analyst', 'root-cause-analyst', 'security-engineer',
+  'system-architect', 'technical-writer',
+]);
+const IMPLEMENTATION_ROLES = new Set([
+  'performance-engineer', 'pm-agent', 'python-expert', 'refactoring-expert',
+]);
+const ALLOWED_FIELDS = new Set([...REQUIRED_FIELDS, 'sandbox_mode']);
+
+function fingerprint(content: string): string {
+  return `sha256:${crypto.createHash('sha256').update(content).digest('hex')}`;
+}
+
+function assertAgentName(name: any, label: string = 'agent name'): string {
+  if (typeof name !== 'string' || !/^[a-z][a-z0-9-]*$/.test(name)) {
+    throw new Error(`${label} must be a lowercase kebab-case identifier`);
+  }
+  return name;
+}
+
+function filenameFor(name: string): string {
+  assertAgentName(name);
+  return `${name}.toml`;
+}
+
+function expectedName(fileName: any): string {
+  if (typeof fileName !== 'string' || path.basename(fileName) !== fileName || !fileName.endsWith('.toml')) {
+    throw new Error('Agent filename must be a direct .toml filename');
+  }
+  return assertAgentName(fileName.slice(0, -'.toml'.length), 'Agent filename');
+}
+
+function parseQuoted(value: string, field: string, line: number): string {
+  if (!/^"(?:[^"\\\n]|\\.)*"$/.test(value)) throw new Error(`${field} must be a quoted TOML string on line ${line}`);
+  try { return JSON.parse(value); } catch { throw new Error(`${field} has an invalid quoted value on line ${line}`); }
+}
+
+/** Parse the intentionally small TOML contract supported by Codex agent definitions. */
+function parseAgentToml(source: any, { fileName }: { fileName?: string } = {}): Record<string, string> {
+  if (typeof source !== 'string') throw new Error('Agent TOML source must be text');
+  const values: Record<string, string> = {};
+  const lines = source.split(/\r?\n/);
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index];
+    if (!line.trim() || /^\s*#/.test(line)) continue;
+    const triple = line.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*"""\s*$/);
+    if (triple) {
+      const field = triple[1];
+      if (!ALLOWED_FIELDS.has(field)) throw new Error(`Unsupported agent field '${field}'`);
+      if (Object.hasOwn(values, field)) throw new Error(`Duplicate agent field '${field}'`);
+      const body: string[] = [];
+      let closed = false;
+      while (++index < lines.length) {
+        if (/^"""\s*$/.test(lines[index])) { closed = true; break; }
+        body.push(lines[index]);
+      }
+      if (!closed) throw new Error(`${field} has an unterminated multiline string`);
+      values[field] = body.join('\n').trim();
+      continue;
+    }
+    const assignment = line.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/);
+    if (!assignment) throw new Error(`Malformed agent TOML on line ${index + 1}`);
+    const [, field, raw] = assignment;
+    if (!ALLOWED_FIELDS.has(field)) throw new Error(`Unsupported agent field '${field}'`);
+    if (Object.hasOwn(values, field)) throw new Error(`Duplicate agent field '${field}'`);
+    values[field] = parseQuoted(raw, field, index + 1);
+  }
+  if (fileName) values._fileName = fileName;
+  return values;
+}
+
+function validateAgentContract(source: any, { fileName }: { fileName?: string } = {}): any {
+  const agent = parseAgentToml(source, { fileName });
+  for (const field of REQUIRED_FIELDS) {
+    if (typeof agent[field] !== 'string' || !agent[field].trim()) throw new Error(`Agent is missing required '${field}'`);
+  }
+  assertAgentName(agent.name);
+  if (fileName && agent.name !== expectedName(fileName)) throw new Error(`Agent name '${agent.name}' must match filename '${fileName}'`);
+  if (agent.description.trim().length < 20) throw new Error(`Agent '${agent.name}' needs a descriptive description`);
+  if (agent.developer_instructions.trim().length < 100) throw new Error(`Agent '${agent.name}' needs substantive developer instructions`);
+  if (agent.sandbox_mode !== undefined && !['read-only', 'workspace-write', 'danger-full-access'].includes(agent.sandbox_mode)) {
+    throw new Error(`Agent '${agent.name}' has an unsupported sandbox_mode`);
+  }
+  if (READ_ONLY_ROLES.has(agent.name) && agent.sandbox_mode !== 'read-only') {
+    throw new Error(`Analysis role '${agent.name}' must use sandbox_mode = "read-only"`);
+  }
+  if (IMPLEMENTATION_ROLES.has(agent.name) && agent.sandbox_mode !== undefined) {
+    throw new Error(`Implementation role '${agent.name}' must inherit its parent sandbox`);
+  }
+  return Object.freeze({ ...agent, fileName: filenameFor(agent.name) });
+}
+
+function agentDirectory({ scope, codexDir, projectRoot, paths }: { scope?: string, codexDir?: string, projectRoot?: string, paths?: any } = {}): string {
+  // Preferred: the declared path resolved by the adapter (harnesses.json "paths".agentsDirectory).
+  if (paths?.agentsDirectory) return paths.agentsDirectory;
+  // Legacy derivation for direct callers passing raw scope inputs; kept byte-compatible with the
+  // declaration the lifecycle path always supplies.
+  if (scope === 'global') {
+    if (!codexDir) throw new Error('codexDir is required for global Codex agents');
+    return path.join(codexDir, AGENT_DIRECTORY);
+  }
+  if (scope === 'project') {
+    if (!projectRoot) throw new Error('projectRoot is required for project Codex agents');
+    return path.join(projectRoot, '.codex', AGENT_DIRECTORY);
+  }
+  throw new Error(`Unsupported Codex agent scope: ${scope}`);
+}
+
+function destinationFor(directory: string, name: string): string {
+  const file = path.resolve(directory, filenameFor(name));
+  const root = `${path.resolve(directory)}${path.sep}`;
+  if (!file.startsWith(root)) throw new Error(`Refusing to write agent '${name}' outside the Codex agents directory`);
+  return file;
+}
+
+function discoverCodexAgents(sourceDir: any, fsImpl: any = fs): any[] {
+  if (!sourceDir) throw new Error('sourceDir is required for Codex agents');
+  const directory = path.resolve(sourceDir);
+  if (!fsImpl.existsSync(directory)) throw new Error(`Codex agent source directory does not exist: ${sourceDir}`);
+  const agents: any[] = [];
+  for (const entry of fsImpl.readdirSync(directory, { withFileTypes: true }).sort((a: any, b: any) => a.name.localeCompare(b.name))) {
+    if (!entry.name.endsWith('.toml')) continue;
+    if (!entry.isFile()) throw new Error(`Codex agent source '${entry.name}' must be a regular file`);
+    const name = expectedName(entry.name);
+    const source = fsImpl.readFileSync(path.join(directory, entry.name), 'utf8');
+    agents.push({ ...validateAgentContract(source, { fileName: entry.name }), name, source, fingerprint: fingerprint(source) });
+  }
+  if (!agents.length) throw new Error(`No Codex agent TOML contracts found in ${sourceDir}`);
+  return agents;
+}
+
+function isOwnedResource(resource: any, scope: any): boolean {
+  return resource && resource.target === 'codex' && resource.scope === scope && resource.kind === AGENT_KIND && typeof resource.identity === 'string';
+}
+
+function resourceFor(agent: any, scope: any, sourceVersion: any): any {
+  return {
+    target: 'codex', scope, kind: AGENT_KIND, identity: `agent:${agent.name}`,
+    sourceVersion, fingerprint: agent.fingerprint, selection: true,
+  };
+}
+
+/** Plan all writes before performing any, preserving unknown or user-modified same-name agents. */
+/**
+ * @param {Object} options
+ * @param {boolean} [options.adopt=false] accept an agent file that exists with no ledger record,
+ *   recording ownership instead of refusing. See planCodexConfig for why this is not `force`: a
+ *   record that disagrees with the file on disk stays a conflict regardless of `adopt`.
+ */
+function planCodexAgents({ scope, codexDir, projectRoot, sourceDir, sourceVersion = 'unknown', managedResources = [], adopt = false, fsImpl = fs }: any): any {
+  const directory = agentDirectory({ scope, codexDir, projectRoot });
+  const agents = discoverCodexAgents(sourceDir, fsImpl);
+  const owned = new Map<string, any>(managedResources.filter((resource: any) => isOwnedResource(resource, scope)).map((resource: any) => [resource.identity, resource]));
+  const changes: any[] = [];
+  const conflicts: string[] = [];
+  const nextManagedResources = managedResources.filter((resource: any) => !isOwnedResource(resource, scope));
+  for (const agent of agents) {
+    const file = destinationFor(directory, agent.name);
+    const identity = `agent:${agent.name}`;
+    const record = owned.get(identity);
+    const current = fsImpl.existsSync(file) ? fsImpl.readFileSync(file, 'utf8') : null;
+    // The chain is written against an explicit `unowned` rather than gating the first branch on
+    // `adopt`, because falling through with `record` undefined would read `record.fingerprint` off
+    // nothing. The `record &&` guard on the drift branch is what makes the adopt path safe.
+    const unowned = current !== null && !record;
+    if (unowned && !adopt) conflicts.push(`Agent '${agent.name}' exists but is not owned by DoFlow`);
+    else if (current !== null && record && record.fingerprint !== fingerprint(current)) conflicts.push(`Agent '${agent.name}' was modified outside DoFlow`);
+    else if (current === null || current !== agent.source) changes.push({ type: current === null ? 'create' : 'update', identity, file, content: agent.source });
+    nextManagedResources.push(resourceFor(agent, scope, sourceVersion));
+  }
+  if (conflicts.length) return { ok: false, status: 'conflict', directory, agents, changes: [], conflicts, managedResources };
+  return {
+    ok: true, status: changes.length ? 'change' : 'unchanged', directory, agents, changes, conflicts: [],
+    managedResources: nextManagedResources,
+  };
+}
+
+function applyCodexAgents(plan: any, { dryRun = false, fsImpl = fs }: { dryRun?: boolean, fsImpl?: any } = {}): any {
+  if (!plan.ok || dryRun || plan.status === 'unchanged') return { ...plan, applied: false };
+  for (const change of plan.changes) atomicWrite(change.file, change.content, fsImpl);
+  return { ...plan, applied: true };
+}
+
+function reconcileCodexAgents(options: any): any {
+  return applyCodexAgents(planCodexAgents(options), options);
+}
+
+module.exports = {
+  AGENT_DIRECTORY, AGENT_KIND, READ_ONLY_ROLES, IMPLEMENTATION_ROLES, fingerprint,
+  parseAgentToml, validateAgentContract, agentDirectory, destinationFor, discoverCodexAgents,
+  planCodexAgents, applyCodexAgents, reconcileCodexAgents,
+};

package/src/adapters/codex/config.ts

@@ -0,0 +1,272 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+// Codex config.toml reconciliation.  This module deliberately manages individual,
+// manifest-backed keys rather than serialising a whole TOML document.  The latter would either
+// require a TOML dependency or, more importantly, risk reformatting/deleting a user's settings.
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const { parseToml, stripComment, tableViolations } = require('../../helper/toml.ts');
+
+const CONFIG_NAME = 'config.toml';
+const CONFIG_KIND = 'configuration-entry';
+
+function configPath({ scope, codexDir, projectRoot, paths }: { scope?: string, codexDir?: string, projectRoot?: string, paths?: any } = {}): string {
+  // Preferred: the declared path resolved by the adapter (harnesses.json "paths".configFile).
+  if (paths?.configFile) return paths.configFile;
+  // Legacy derivation for direct callers passing raw scope inputs (tests, reconcileCodexConfig);
+  // kept byte-compatible with the declaration the lifecycle path always supplies.
+  if (scope === 'global') {
+    if (!codexDir) throw new Error('codexDir is required for global Codex configuration');
+    return path.join(codexDir, CONFIG_NAME);
+  }
+  if (scope === 'project') {
+    if (!projectRoot) throw new Error('projectRoot is required for project Codex configuration');
+    return path.join(projectRoot, '.codex', CONFIG_NAME);
+  }
+  throw new Error(`Unsupported Codex configuration scope: ${scope}`);
+}
+
+function fingerprint(value: any): string {
+  return `sha256:${crypto.createHash('sha256').update(JSON.stringify(value)).digest('hex')}`;
+}
+
+function commentSuffix(line: string): string {
+  const withoutComment = stripComment(line);
+  return line.slice(withoutComment.length);
+}
+
+function renderValue(value: any): string {
+  if (typeof value === 'boolean' || typeof value === 'number') return String(value);
+  if (typeof value === 'string') return JSON.stringify(value);
+  throw new Error('Managed Codex config values must be boolean, number, or string');
+}
+
+function normaliseDesired(resources: any): Map<string, any> {
+  const result = new Map<string, any>();
+  for (const resource of resources || []) {
+    if (!resource || (resource.kind && resource.kind !== CONFIG_KIND && resource.kind !== 'config-entry')) continue;
+    const identity = resource.identity ?? resource.key;
+    if (!identity || !/^[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)+$/.test(identity)) {
+      throw new Error('A managed Codex configuration resource requires a dotted identity');
+    }
+    if (!Object.hasOwn(resource, 'value')) throw new Error(`Managed Codex configuration '${identity}' requires a value`);
+    renderValue(resource.value);
+    if (result.has(identity)) throw new Error(`Duplicate desired Codex configuration resource '${identity}'`);
+    result.set(identity, { ...resource, identity, kind: resource.kind ?? CONFIG_KIND });
+  }
+  return result;
+}
+
+/** The comment on a line DoFlow added to a table the user opened with no entry: it is how removal
+ * knows to keep the user's header and restore the file's exact bytes. */
+function addedMarker(table: string): string { return ` # DoFlow added this to your [${table}] table`; }
+
+/** Where a new entry `<table>.<key>` goes in the parsed file: after the last entry of its table;
+ * on the line right after the table's empty header, marked; as a root dotted line after the last
+ * root dotted line of that table; refused (`valueEntry`) when the table or a parent of it is set as
+ * a value, which TOML cannot extend; otherwise in a new table (no `at`). */
+function placeEntry(identity: string, value: any, parsed: any): any {
+  const parts = identity.split('.');
+  const table = parts.slice(0, -1).join('.');
+  const rendered = renderValue(value);
+  const assignment = `${parts.at(-1)} = ${rendered}`;
+  const entries: any[] = [...parsed.entries];
+  const after = (items: any[]) => Math.max(...items.map(([, entry]: any) => entry.line)) + 1;
+  const inTable = entries.filter(([, entry]: any) => entry.table === table);
+  if (inTable.length) return { table, at: after(inTable), line: assignment };
+  const header = parsed.headers.find((item: any) => item.table === table);
+  if (header) return { table, at: header.line + 1, line: `${assignment}${addedMarker(table)}` };
+  const dotted = entries.filter(([key, entry]: any) => entry.table === '' && key.startsWith(`${table}.`));
+  if (dotted.length) return { table, at: after(dotted), line: `${identity} = ${rendered}` };
+  const valueEntry = entries.find(([key]: any) => key === table || table.startsWith(`${key}.`));
+  if (valueEntry) return { table, valueEntry };
+  return { table, line: assignment };
+}
+
+/** Whether a managed entry's line is one placeEntry put into the user's own table: marked, or
+ * written as a dotted key outside its table. */
+function placedLine(identity: string, entry: any, lines: any[]): boolean {
+  const table = identity.split('.').slice(0, -1).join('.');
+  return entry.table !== table || lines[entry.line].trimEnd().endsWith(addedMarker(table));
+}
+
+/** A conflict when `content` breaks a TOML table rule that `original` did not already break, so a
+ * file that was valid is never written invalid; null otherwise. */
+function newViolation({ file, original, content, identities }: { file: string, original: string, content: string, identities: string[] }): string | null {
+  const refused = (reason: string) => `${file}: DoFlow cannot write ${identities.map((identity) => `'${identity}'`).join(', ')} without making the file invalid TOML (${reason}). Nothing was written.`;
+  const before = tableViolations(original);
+  let after;
+  try { after = tableViolations(content); } catch (error: any) { return refused(error.message); }
+  const added = after.find((item: any) => !before.some((known: any) => known.kind === item.kind && known.table === item.table));
+  return added ? refused(`${added.kind} '${added.table}' on line ${added.line}`) : null;
+}
+
+function isOwnedRecord(resource: any, scope: any): boolean {
+  return resource && resource.target === 'codex' && resource.scope === scope &&
+    (resource.kind === CONFIG_KIND || resource.kind === 'config-entry') && typeof resource.identity === 'string';
+}
+
+/**
+ * @param {Object} options
+ * @param {boolean} [options.adopt=false] accept a config entry that exists with no ledger record,
+ *   recording ownership of it instead of refusing. Distinct from `force`, which overrides a record
+ *   that *disagrees* with the file: adoption only ever covers the no-record case, and a resource
+ *   whose record contradicts its bytes stays a conflict here whatever `adopt` says. Without this,
+ *   entries written before the neutral ledger existed could never be re-adopted — the condition
+ *   blocking the install was the same condition an install had to run to clear.
+ */
+function planCodexConfig({ file, scope, managedResources = [], desiredResources = [], adopt = false }: { file: string, scope?: any, managedResources?: any[], desiredResources?: any[], adopt?: boolean }): any {
+  const original = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  let parsed;
+  try { parsed = parseToml(original); } catch (error: any) {
+    return { ok: false, status: 'malformed', file, original, changes: [], conflicts: [error.message], managedResources };
+  }
+  let desired;
+  try { desired = normaliseDesired(desiredResources); } catch (error: any) {
+    return { ok: false, status: 'invalid-request', file, original, changes: [], conflicts: [error.message], managedResources };
+  }
+  const owned = new Map<string, any>(managedResources.filter((resource: any) => isOwnedRecord(resource, scope)).map((resource: any) => [resource.identity, resource]));
+  const changes: any[] = [];
+  const conflicts: string[] = [];
+  const placements = new Map<string, any>();
+  const all = new Set([...desired.keys(), ...owned.keys()]);
+  for (const identity of all) {
+    const entry = parsed.entries.get(identity);
+    const record = owned.get(identity);
+    const wanted = desired.get(identity);
+    if (!record && entry && !adopt) {
+      conflicts.push(`'${identity}' exists but is not owned by DoFlow`);
+      continue;
+    }
+    // Adopting: no `continue`, so the entry goes through ordinary planning below. Ownership is
+    // recorded either way — `nextManagedResources` is rebuilt from `desired` regardless of what was
+    // owned before — so adoption needs nothing beyond not refusing here.
+    if (record && entry && record.fingerprint !== fingerprint(entry.value)) {
+      conflicts.push(`'${identity}' was modified outside DoFlow`);
+      continue;
+    }
+    if (wanted && (!entry || fingerprint(entry.value) !== fingerprint(wanted.value))) {
+      changes.push({ type: entry ? 'update' : 'create', identity, value: wanted.value, line: entry?.line });
+      if (!entry) {
+        const placement = placeEntry(identity, wanted.value, parsed);
+        if (placement.valueEntry) {
+          const [prefix, held] = placement.valueEntry;
+          conflicts.push(`${file}: '${prefix}' is set as a value on line ${held.line + 1}, so DoFlow cannot add '${identity}' to it. Write it as a [${prefix}] table and run the command again. Nothing was written.`);
+        }
+        placements.set(identity, placement);
+      }
+    } else if (!wanted && entry) {
+      changes.push({ type: 'remove', identity, line: entry.line });
+    }
+  }
+  if (conflicts.length) return { ok: false, status: 'conflict', file, original, changes: [], conflicts, managedResources };
+  const nextLines = [...parsed.lines];
+  for (const change of changes.filter((change: any) => change.type === 'update')) {
+    const key = change.identity.split('.').at(-1);
+    const originalLine = nextLines[change.line];
+    const indentation = originalLine.match(/^\s*/)![0];
+    // A user comment beside an owned value is still user content. Retain it even though the
+    // owned scalar changes, so reconciliation does not silently erase unrelated explanation.
+    const suffix = commentSuffix(originalLine);
+    nextLines[change.line] = `${indentation}${key} = ${renderValue(change.value)}${suffix && !/^\s/.test(suffix) ? ' ' : ''}${suffix}`;
+  }
+  // A line DoFlow placed in the user's own table (marker or dotted form) is deleted outright and its
+  // header kept, so the file returns to its exact bytes. Any other removal leaves a blank line.
+  const removals = changes.filter((change: any) => change.type === 'remove');
+  const placedInUserTable = removals.filter((change: any) => placedLine(change.identity, parsed.entries.get(change.identity), parsed.lines));
+  for (const change of removals) nextLines[change.line] = placedInUserTable.includes(change) ? null : '';
+  dropEmptiedTables(nextLines, changes.filter((change: any) => !placedInUserTable.includes(change)), parsed.headers);
+  // A new key must land INSIDE its own table. Appending at end-of-file only happens to be
+  // correct when that table is the file's last one — otherwise the key silently joins whichever
+  // table trails the file, so `features.hooks` written after an `[mcp_servers.x]` block becomes
+  // `mcp_servers.x.hooks`. placeEntry chooses the spot; genuinely new tables are appended once
+  // each, with all of their keys grouped under a single header.
+  const insertions: { at: number, line: string }[] = [];
+  const newTables = new Map<string, string[]>();
+  for (const change of changes.filter((change: any) => change.type === 'create')) {
+    const placement = placements.get(change.identity);
+    if (placement.at !== undefined) insertions.push({ at: placement.at, line: placement.line });
+    else newTables.set(placement.table, [...(newTables.get(placement.table) || []), placement.line]);
+  }
+  // Descending, so an earlier insertion never shifts the index of one still pending.
+  for (const insertion of insertions.sort((a, b) => b.at - a.at)) nextLines.splice(insertion.at, 0, insertion.line);
+  // Dropped lines were kept as null placeholders so the insertion indices above stayed valid.
+  for (let index = nextLines.length - 1; index >= 0; index--) if (nextLines[index] === null) nextLines.splice(index, 1);
+  for (const [table, lines] of newTables) {
+    // `''.split(/\r?\n/)` is [`''`]; drop that synthetic line so a brand-new file does
+    // not start with an unintended blank line.
+    if (nextLines.length === 1 && nextLines[0] === '') nextLines.pop();
+    if (nextLines.length && nextLines.at(-1) !== '') nextLines.push('');
+    nextLines.push(`[${table}]`, ...lines);
+  }
+  let content = nextLines.join('\n');
+  if (content && !content.endsWith('\n')) content += '\n';
+  const invalid = newViolation({ file, original, content, identities: changes.map((change: any) => change.identity) });
+  if (invalid) return { ok: false, status: 'conflict', file, original, changes: [], conflicts: [invalid], managedResources };
+  const nextManagedResources = managedResources.filter((resource: any) => !isOwnedRecord(resource, scope) || desired.has(resource.identity));
+  for (const resource of desired.values()) {
+    const index = nextManagedResources.findIndex((item: any) => isOwnedRecord(item, scope) && item.identity === resource.identity);
+    const updated = { ...resource, target: 'codex', scope, kind: CONFIG_KIND, fingerprint: fingerprint(resource.value) };
+    if (index >= 0) nextManagedResources[index] = updated;
+    else nextManagedResources.push(updated);
+  }
+  return { ok: true, status: changes.length ? 'change' : 'unchanged', file, original, content, changes, conflicts: [], managedResources: nextManagedResources };
+}
+
+/** A table whose every key this plan removed, with nothing else under its header (no user key or
+ * comment), is DoFlow's own leftover: its header and removed lines become null placeholders. When
+ * it was the file's last table, the blank line the table append puts before a new header goes too.
+ * A table that also receives a created key, or whose header line carries a comment, is kept.
+ * Headers come from the parser's own records, never from re-reading lines. */
+function dropEmptiedTables(lines: any[], changes: any[], headerRecords: any[]): void {
+  const tableOf = (identity: string) => identity.split('.').slice(0, -1).join('.');
+  const removedTables = new Map<number, string>(changes.filter((change) => change.type === 'remove').map((change): [number, string] => [change.line, tableOf(change.identity)]));
+  const createdTables = new Set<string>(changes.filter((change) => change.type === 'create').map((change) => tableOf(change.identity)));
+  const headers: number[] = headerRecords.map((header) => header.line);
+  headers.forEach((start, position) => {
+    const end = headers[position + 1] ?? lines.length;
+    if (stripComment(lines[start]) !== lines[start]) return;
+    const body = lines.slice(start + 1, end).map((_: any, offset: number) => start + 1 + offset);
+    const removedHere = body.filter((index) => removedTables.has(index));
+    if (!removedHere.length || removedHere.some((index) => createdTables.has(removedTables.get(index) as string))) return;
+    if (body.some((index) => !removedTables.has(index) && lines[index] !== null && lines[index].trim() !== '')) return;
+    lines[start] = null;
+    for (const index of removedHere) lines[index] = null;
+    if (end === lines.length && start > 0 && lines[start - 1] === '') lines[start - 1] = null;
+  });
+}
+
+/** Replace a file through a sibling temporary file, keeping the existing file's permission bits so
+ * a config kept private stays so. A file this creates gets the process's default mode. */
+function atomicWrite(file: string, content: string, fsImpl: any = fs): void {
+  fsImpl.mkdirSync(path.dirname(file), { recursive: true });
+  const mode = fsImpl.existsSync(file) ? fsImpl.statSync(file).mode & 0o7777 : null;
+  const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${Date.now()}.tmp`);
+  try {
+    fsImpl.writeFileSync(temporary, content, { flag: 'wx', ...(mode === null ? {} : { mode }) });
+    if (mode !== null) fsImpl.chmodSync(temporary, mode);
+    fsImpl.renameSync(temporary, file);
+  } finally {
+    if (fsImpl.existsSync(temporary)) fsImpl.unlinkSync(temporary);
+  }
+}
+
+function applyCodexConfig(plan: any, { dryRun = false, fsImpl = fs }: { dryRun?: boolean, fsImpl?: any } = {}): any {
+  if (!plan.ok) return { ...plan, applied: false };
+  if (dryRun || plan.status === 'unchanged') return { ...plan, applied: false };
+  // A removal that leaves nothing behind deletes the file rather than leaving it empty.
+  if (plan.content === '') { if (fsImpl.existsSync(plan.file)) fsImpl.unlinkSync(plan.file); }
+  else atomicWrite(plan.file, plan.content, fsImpl);
+  return { ...plan, applied: true };
+}
+
+function reconcileCodexConfig(options: any): any {
+  const file = options.file ?? configPath(options);
+  const plan = planCodexConfig({ ...options, file });
+  return applyCodexConfig(plan, options);
+}
+
+module.exports = { CONFIG_NAME, CONFIG_KIND, configPath, fingerprint, parseToml, newViolation, planCodexConfig, applyCodexConfig, reconcileCodexConfig, atomicWrite };