@myclaw163/clawclaw-cli 0.6.70 → 0.6.74

package/src/lib/game-context.ts

@@ -0,0 +1,92 @@
+import { readFileSync } from 'fs';
+
+function finiteNumber(value: unknown): number | undefined {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string' && value.trim() !== '') {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return undefined;
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+function cleanObject<T extends Record<string, any>>(obj: T): T {
+  for (const key of Object.keys(obj)) {
+    if (obj[key] === undefined) delete obj[key];
+  }
+  return obj;
+}
+
+export function briefGameMap(mapData: any): any {
+  if (!mapData) return null;
+  return {
+    rooms: mapData.rooms?.map((r: any) => ({
+      name: r.name,
+      polygon: r.polygon,
+    })),
+  };
+}
+
+export function taskLocations(mapData: any): { lobster: any[]; crab: any[] } {
+  const output = { lobster: [] as any[], crab: [] as any[] };
+  for (const task of Array.isArray(mapData?.all_task_locations) ? mapData.all_task_locations : []) {
+    const item = cleanObject({
+      name: task.name,
+      room: task.room,
+      x: task.x,
+      y: task.y,
+    });
+    if (task.faction === 'crab') output.crab.push(item);
+    else output.lobster.push(item);
+  }
+  return output;
+}
+
+export function loadAsciiMapAsset(): string | null {
+  try {
+    return readFileSync(new URL('../assets/clawclaw-ascii-map.txt', import.meta.url), 'utf8').trimEnd();
+  } catch {
+    return null;
+  }
+}
+
+export function summarizeGameMap(mapData: any, opts?: { ascii?: boolean }): any {
+  const output: Record<string, any> = {
+    rooms: mapData?.rooms?.map((r: any) => ({
+      name: r.name,
+      polygon: r.polygon,
+    })) ?? [],
+    task_locations: taskLocations(mapData),
+  };
+  if (opts?.ascii) output.ascii_map = loadAsciiMapAsset();
+  return output;
+}
+
+export function playersFromMap(mapData: any): Array<{ name: string; seat: number }> {
+  const players: Array<{ name: string; seat: number }> = [];
+  for (const player of Array.isArray(mapData?.all_players) ? mapData.all_players : []) {
+    const name = nonEmptyString(player?.name ?? player?.agent_name);
+    const seat = finiteNumber(player?.seat);
+    if (!name || seat === undefined) continue;
+    players.push({ name, seat });
+  }
+  return players;
+}
+
+export function seatMapFromPlayers(players: Array<{ name: string; seat: number }>): Record<string, number> {
+  const seats: Record<string, number> = {};
+  for (const player of players) seats[player.name] = player.seat;
+  return seats;
+}
+
+export function buildGameStartedEnrichment(mapData: any): Record<string, any> {
+  const players = playersFromMap(mapData);
+  return cleanObject({
+    players: players.length > 0 ? players : undefined,
+    all_seats: players.length > 0 ? seatMapFromPlayers(players) : undefined,
+    map: summarizeGameMap(mapData, { ascii: true }),
+  });
+}

package/src/lib/host-config-patcher.test.ts

@@ -1,130 +1,130 @@
-import { mkdtempSync, readFileSync, writeFileSync, existsSync, readdirSync } from 'fs';
-import { tmpdir } from 'os';
-import { dirname, join } from 'path';
-import { describe, expect, it } from 'vitest';
-import { runHostConfigSetup, unionArrayField, type HostConfigPatcher } from './host-config-patcher.js';
-
-function tmpConfig(initial: unknown): string {
-  const dir = mkdtempSync(join(tmpdir(), 'host-cfg-'));
-  const p = join(dir, 'config.json');
-  writeFileSync(p, JSON.stringify(initial, null, 2));
-  return p;
-}
-
-const dummyHost: HostConfigPatcher<{ value: string }> = {
-  hostName: 'dummy',
-  resolveConfigPath: () => '/tmp/never-used',
-  computePatch: (current, opts) => {
-    const cur = (current as Record<string, unknown> | null) ?? {};
-    const before = (cur.values as string[] | undefined) ?? [];
-    if (before.includes(opts.value)) return { next: cur, changes: [], warnings: [] };
-    return {
-      next: { ...cur, values: [...before, opts.value] },
-      changes: [`add ${opts.value} to values`],
-      warnings: [],
-    };
-  },
-};
-
-describe('runHostConfigSetup', () => {
-  it('prints recommended patch in --print mode without touching disk', () => {
-    const r = runHostConfigSetup(dummyHost, { value: 'x' }, { print: true });
-    expect(r.exitCode).toBe(0);
-    expect(r.output.join('\n')).toContain('"values"');
-  });
-
-  it('reports missing config file gracefully', () => {
-    const r = runHostConfigSetup(dummyHost, { value: 'x' }, { configPath: '/no/such/file.json' });
-    expect(r.exitCode).toBe(0);
-    expect(r.output.some((l) => l.includes('not found'))).toBe(true);
-  });
-
-  it('reports malformed JSON with exit 1', () => {
-    const dir = mkdtempSync(join(tmpdir(), 'host-cfg-bad-'));
-    const p = join(dir, 'config.json');
-    writeFileSync(p, '{ not: valid json');
-    const r = runHostConfigSetup(dummyHost, { value: 'x' }, { configPath: p });
-    expect(r.exitCode).toBe(1);
-    expect(r.output.join('\n')).toMatch(/Failed to parse/);
-  });
-
-  it('returns exit 2 with diff in dry-run when changes pending', () => {
-    const p = tmpConfig({ values: ['a'] });
-    const r = runHostConfigSetup(dummyHost, { value: 'b' }, { configPath: p });
-    expect(r.exitCode).toBe(2);
-    const txt = r.output.join('\n');
-    expect(txt).toMatch(/Pending changes/);
-    expect(txt).toMatch(/Re-run with -y to apply/);
-    // file unchanged
-    expect(JSON.parse(readFileSync(p, 'utf-8'))).toEqual({ values: ['a'] });
-  });
-
-  it('returns exit 0 no-op when already up to date', () => {
-    const p = tmpConfig({ values: ['a'] });
-    const r = runHostConfigSetup(dummyHost, { value: 'a' }, { configPath: p });
-    expect(r.exitCode).toBe(0);
-    expect(r.output.join('\n')).toMatch(/already up to date/);
-  });
-
-  it('applies changes atomically with backup when -y', () => {
-    const p = tmpConfig({ values: ['a'] });
-    const r = runHostConfigSetup(dummyHost, { value: 'b' }, { configPath: p, yes: true });
-    expect(r.exitCode).toBe(0);
-    expect(JSON.parse(readFileSync(p, 'utf-8'))).toEqual({ values: ['a', 'b'] });
-    const files = readdirSync(dirname(p));
-    expect(files.some((f) => f.startsWith('config.json.bak.'))).toBe(true);
-  });
-
-  it('--no-backup skips backup file', () => {
-    const p = tmpConfig({ values: ['a'] });
-    const r = runHostConfigSetup(dummyHost, { value: 'b' }, { configPath: p, yes: true, backup: false });
-    expect(r.exitCode).toBe(0);
-    const files = readdirSync(dirname(p));
-    expect(files.some((f) => f.startsWith('config.json.bak.'))).toBe(false);
-  });
-
-  it('does not leave .tmp file behind on success', () => {
-    const p = tmpConfig({ values: ['a'] });
-    runHostConfigSetup(dummyHost, { value: 'b' }, { configPath: p, yes: true, backup: false });
-    const files = readdirSync(dirname(p));
-    expect(files.some((f) => f.includes('.tmp.'))).toBe(false);
-  });
-
-  it('preserves CRLF line endings when original file uses CRLF', () => {
-    const dir = mkdtempSync(join(tmpdir(), 'host-cfg-crlf-'));
-    const p = join(dir, 'config.json');
-    writeFileSync(p, '{\r\n  "values": [\r\n    "a"\r\n  ]\r\n}\r\n');
-    runHostConfigSetup(dummyHost, { value: 'b' }, { configPath: p, yes: true, backup: false });
-    const after = readFileSync(p, 'utf-8');
-    expect(after.includes('\r\n')).toBe(true);
-    expect(after.replace(/\r\n/g, '<EOL>').includes('\n')).toBe(false);
-  });
-
-  it('preserves LF line endings when original file uses LF', () => {
-    const dir = mkdtempSync(join(tmpdir(), 'host-cfg-lf-'));
-    const p = join(dir, 'config.json');
-    writeFileSync(p, '{\n  "values": [\n    "a"\n  ]\n}\n');
-    runHostConfigSetup(dummyHost, { value: 'b' }, { configPath: p, yes: true, backup: false });
-    const after = readFileSync(p, 'utf-8');
-    expect(after.includes('\r\n')).toBe(false);
-  });
-});
-
-describe('unionArrayField', () => {
-  it('creates new array when field missing', () => {
-    expect(unionArrayField(undefined, 'x')).toEqual({ next: ['x'], added: true });
-  });
-
-  it('returns warning when existing value is not an array', () => {
-    const r = unionArrayField('not-an-array', 'x');
-    expect(r).toEqual({ warning: 'existing value is not an array, refusing to overwrite' });
-  });
-
-  it('returns added=false when entry already present', () => {
-    expect(unionArrayField(['a', 'b'], 'a')).toEqual({ next: ['a', 'b'], added: false });
-  });
-
-  it('appends entry when missing from array', () => {
-    expect(unionArrayField(['a'], 'b')).toEqual({ next: ['a', 'b'], added: true });
-  });
-});
+import { mkdtempSync, readFileSync, writeFileSync, existsSync, readdirSync } from 'fs';
+import { tmpdir } from 'os';
+import { dirname, join } from 'path';
+import { describe, expect, it } from 'vitest';
+import { runHostConfigSetup, unionArrayField, type HostConfigPatcher } from './host-config-patcher.js';
+
+function tmpConfig(initial: unknown): string {
+  const dir = mkdtempSync(join(tmpdir(), 'host-cfg-'));
+  const p = join(dir, 'config.json');
+  writeFileSync(p, JSON.stringify(initial, null, 2));
+  return p;
+}
+
+const dummyHost: HostConfigPatcher<{ value: string }> = {
+  hostName: 'dummy',
+  resolveConfigPath: () => '/tmp/never-used',
+  computePatch: (current, opts) => {
+    const cur = (current as Record<string, unknown> | null) ?? {};
+    const before = (cur.values as string[] | undefined) ?? [];
+    if (before.includes(opts.value)) return { next: cur, changes: [], warnings: [] };
+    return {
+      next: { ...cur, values: [...before, opts.value] },
+      changes: [`add ${opts.value} to values`],
+      warnings: [],
+    };
+  },
+};
+
+describe('runHostConfigSetup', () => {
+  it('prints recommended patch in --print mode without touching disk', () => {
+    const r = runHostConfigSetup(dummyHost, { value: 'x' }, { print: true });
+    expect(r.exitCode).toBe(0);
+    expect(r.output.join('\n')).toContain('"values"');
+  });
+
+  it('reports missing config file gracefully', () => {
+    const r = runHostConfigSetup(dummyHost, { value: 'x' }, { configPath: '/no/such/file.json' });
+    expect(r.exitCode).toBe(0);
+    expect(r.output.some((l) => l.includes('not found'))).toBe(true);
+  });
+
+  it('reports malformed JSON with exit 1', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'host-cfg-bad-'));
+    const p = join(dir, 'config.json');
+    writeFileSync(p, '{ not: valid json');
+    const r = runHostConfigSetup(dummyHost, { value: 'x' }, { configPath: p });
+    expect(r.exitCode).toBe(1);
+    expect(r.output.join('\n')).toMatch(/Failed to parse/);
+  });
+
+  it('returns exit 2 with diff in dry-run when changes pending', () => {
+    const p = tmpConfig({ values: ['a'] });
+    const r = runHostConfigSetup(dummyHost, { value: 'b' }, { configPath: p });
+    expect(r.exitCode).toBe(2);
+    const txt = r.output.join('\n');
+    expect(txt).toMatch(/Pending changes/);
+    expect(txt).toMatch(/Re-run with -y to apply/);
+    // file unchanged
+    expect(JSON.parse(readFileSync(p, 'utf-8'))).toEqual({ values: ['a'] });
+  });
+
+  it('returns exit 0 no-op when already up to date', () => {
+    const p = tmpConfig({ values: ['a'] });
+    const r = runHostConfigSetup(dummyHost, { value: 'a' }, { configPath: p });
+    expect(r.exitCode).toBe(0);
+    expect(r.output.join('\n')).toMatch(/already up to date/);
+  });
+
+  it('applies changes atomically with backup when -y', () => {
+    const p = tmpConfig({ values: ['a'] });
+    const r = runHostConfigSetup(dummyHost, { value: 'b' }, { configPath: p, yes: true });
+    expect(r.exitCode).toBe(0);
+    expect(JSON.parse(readFileSync(p, 'utf-8'))).toEqual({ values: ['a', 'b'] });
+    const files = readdirSync(dirname(p));
+    expect(files.some((f) => f.startsWith('config.json.bak.'))).toBe(true);
+  });
+
+  it('--no-backup skips backup file', () => {
+    const p = tmpConfig({ values: ['a'] });
+    const r = runHostConfigSetup(dummyHost, { value: 'b' }, { configPath: p, yes: true, backup: false });
+    expect(r.exitCode).toBe(0);
+    const files = readdirSync(dirname(p));
+    expect(files.some((f) => f.startsWith('config.json.bak.'))).toBe(false);
+  });
+
+  it('does not leave .tmp file behind on success', () => {
+    const p = tmpConfig({ values: ['a'] });
+    runHostConfigSetup(dummyHost, { value: 'b' }, { configPath: p, yes: true, backup: false });
+    const files = readdirSync(dirname(p));
+    expect(files.some((f) => f.includes('.tmp.'))).toBe(false);
+  });
+
+  it('preserves CRLF line endings when original file uses CRLF', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'host-cfg-crlf-'));
+    const p = join(dir, 'config.json');
+    writeFileSync(p, '{\r\n  "values": [\r\n    "a"\r\n  ]\r\n}\r\n');
+    runHostConfigSetup(dummyHost, { value: 'b' }, { configPath: p, yes: true, backup: false });
+    const after = readFileSync(p, 'utf-8');
+    expect(after.includes('\r\n')).toBe(true);
+    expect(after.replace(/\r\n/g, '<EOL>').includes('\n')).toBe(false);
+  });
+
+  it('preserves LF line endings when original file uses LF', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'host-cfg-lf-'));
+    const p = join(dir, 'config.json');
+    writeFileSync(p, '{\n  "values": [\n    "a"\n  ]\n}\n');
+    runHostConfigSetup(dummyHost, { value: 'b' }, { configPath: p, yes: true, backup: false });
+    const after = readFileSync(p, 'utf-8');
+    expect(after.includes('\r\n')).toBe(false);
+  });
+});
+
+describe('unionArrayField', () => {
+  it('creates new array when field missing', () => {
+    expect(unionArrayField(undefined, 'x')).toEqual({ next: ['x'], added: true });
+  });
+
+  it('returns warning when existing value is not an array', () => {
+    const r = unionArrayField('not-an-array', 'x');
+    expect(r).toEqual({ warning: 'existing value is not an array, refusing to overwrite' });
+  });
+
+  it('returns added=false when entry already present', () => {
+    expect(unionArrayField(['a', 'b'], 'a')).toEqual({ next: ['a', 'b'], added: false });
+  });
+
+  it('appends entry when missing from array', () => {
+    expect(unionArrayField(['a'], 'b')).toEqual({ next: ['a', 'b'], added: true });
+  });
+});

package/src/lib/host-config-patcher.ts

@@ -1,151 +1,151 @@
-/**
- * Generic JSON-config setup runner shared by `ccl setup <host>` subcommands.
- *
- * Each host adapter only supplies:
- *   - resolveConfigPath(): where the host stores its global JSON config
- *   - computePatch(current, opts): pure function returning the desired next config + change/warning notes
- *
- * The runner handles dry-run, diff, atomic write, and timestamped backup uniformly,
- * so adding a new host (gemini, claude-code, ...) is ~30 lines of glue.
- */
-
-import { existsSync, readFileSync, renameSync, copyFileSync, writeFileSync } from 'fs';
-
-export interface HostConfigPatcher<Opts extends object = Record<string, never>> {
-  hostName: string;
-  resolveConfigPath: () => string;
-  computePatch: (current: unknown, opts: Opts) => HostPatchResult;
-}
-
-export interface HostPatchResult {
-  next: unknown;
-  changes: string[];
-  warnings: string[];
-}
-
-export interface RunHostSetupFlags {
-  yes?: boolean;
-  print?: boolean;
-  configPath?: string;
-  backup?: boolean;
-}
-
-export interface RunHostSetupResult {
-  exitCode: number;
-  output: string[];
-}
-
-export function runHostConfigSetup<Opts extends object>(
-  patcher: HostConfigPatcher<Opts>,
-  hostOpts: Opts,
-  flags: RunHostSetupFlags,
-): RunHostSetupResult {
-  const out: string[] = [];
-  const configPath = flags.configPath ?? patcher.resolveConfigPath();
-
-  if (flags.print) {
-    const sample = patcher.computePatch({}, hostOpts);
-    out.push(`# Recommended ${patcher.hostName} config patch:`);
-    out.push(JSON.stringify(sample.next, null, 2));
-    return { exitCode: 0, output: out };
-  }
-
-  if (!existsSync(configPath)) {
-    out.push(`${patcher.hostName} config not found at: ${configPath}`);
-    out.push(`Initialize it first (e.g. \`openclaw doctor\` for OpenClaw), then re-run.`);
-    return { exitCode: 0, output: out };
-  }
-
-  let raw: string;
-  try {
-    raw = readFileSync(configPath, 'utf-8');
-  } catch (err: any) {
-    out.push(`Failed to read ${configPath}: ${err?.message ?? err}`);
-    return { exitCode: 1, output: out };
-  }
-
-  let current: unknown;
-  try {
-    current = JSON.parse(raw);
-  } catch (err: any) {
-    out.push(`Failed to parse JSON at ${configPath}: ${err?.message ?? err}`);
-    out.push(`Fix the JSON manually first; this tool does not edit malformed files.`);
-    return { exitCode: 1, output: out };
-  }
-
-  const { next, changes, warnings } = patcher.computePatch(current, hostOpts);
-
-  for (const w of warnings) out.push(`warning: ${w}`);
-
-  if (changes.length === 0) {
-    out.push(`${patcher.hostName} config already up to date at ${configPath}.`);
-    return { exitCode: 0, output: out };
-  }
-
-  if (!flags.yes) {
-    out.push(`Pending changes to ${configPath}:`);
-    for (const c of changes) out.push(`  - ${c}`);
-    out.push(``);
-    out.push(diffJson(current, next));
-    out.push(``);
-    out.push(`Dry-run only. Re-run with -y to apply.`);
-    return { exitCode: 2, output: out };
-  }
-
-  let backupPath: string | undefined;
-  if (flags.backup !== false) {
-    const ts = new Date().toISOString().replace(/[:.]/g, '-');
-    backupPath = `${configPath}.bak.${ts}`;
-    try {
-      copyFileSync(configPath, backupPath);
-    } catch (err: any) {
-      out.push(`Failed to back up ${configPath} → ${backupPath}: ${err?.message ?? err}`);
-      return { exitCode: 1, output: out };
-    }
-  }
-
-  const tmpPath = `${configPath}.tmp.${process.pid}`;
-  try {
-    const eol = raw.includes('\r\n') ? '\r\n' : '\n';
-    const serialized = JSON.stringify(next, null, 2).replace(/\n/g, eol) + eol;
-    writeFileSync(tmpPath, serialized, 'utf-8');
-    renameSync(tmpPath, configPath);
-  } catch (err: any) {
-    out.push(`Failed to write ${configPath}: ${err?.message ?? err}`);
-    return { exitCode: 1, output: out };
-  }
-
-  out.push(`Updated ${configPath}:`);
-  for (const c of changes) out.push(`  - ${c}`);
-  if (backupPath) out.push(`Backup: ${backupPath}`);
-  return { exitCode: 0, output: out };
-}
-
-/** Minimal line-level JSON diff for the dry-run preview. Self-contained, zero deps. */
-export function diffJson(before: unknown, after: unknown): string {
-  const a = JSON.stringify(before, null, 2).split('\n');
-  const b = JSON.stringify(after, null, 2).split('\n');
-  const aSet = new Set(a);
-  const bSet = new Set(b);
-  const lines: string[] = [];
-  const max = Math.max(a.length, b.length);
-  for (let i = 0; i < max; i++) {
-    const ax = a[i];
-    const bx = b[i];
-    if (ax === bx) {
-      lines.push(`  ${ax ?? ''}`);
-    } else {
-      if (ax !== undefined && !bSet.has(ax)) lines.push(`- ${ax}`);
-      if (bx !== undefined && !aSet.has(bx)) lines.push(`+ ${bx}`);
-    }
-  }
-  return lines.join('\n');
-}
-
-/** Shared helper for hosts: add an entry to an array field, returning a new array (Set union). */
-export function unionArrayField(arr: unknown, entry: string): { next: string[]; added: boolean } | { warning: string } {
-  if (arr === undefined) return { next: [entry], added: true };
-  if (!Array.isArray(arr)) return { warning: `existing value is not an array, refusing to overwrite` };
-  if (arr.includes(entry)) return { next: arr.slice() as string[], added: false };
-  return { next: [...(arr as string[]), entry], added: true };
-}
+/**
+ * Generic JSON-config setup runner shared by `ccl setup <host>` subcommands.
+ *
+ * Each host adapter only supplies:
+ *   - resolveConfigPath(): where the host stores its global JSON config
+ *   - computePatch(current, opts): pure function returning the desired next config + change/warning notes
+ *
+ * The runner handles dry-run, diff, atomic write, and timestamped backup uniformly,
+ * so adding a new host (gemini, claude-code, ...) is ~30 lines of glue.
+ */
+
+import { existsSync, readFileSync, renameSync, copyFileSync, writeFileSync } from 'fs';
+
+export interface HostConfigPatcher<Opts extends object = Record<string, never>> {
+  hostName: string;
+  resolveConfigPath: () => string;
+  computePatch: (current: unknown, opts: Opts) => HostPatchResult;
+}
+
+export interface HostPatchResult {
+  next: unknown;
+  changes: string[];
+  warnings: string[];
+}
+
+export interface RunHostSetupFlags {
+  yes?: boolean;
+  print?: boolean;
+  configPath?: string;
+  backup?: boolean;
+}
+
+export interface RunHostSetupResult {
+  exitCode: number;
+  output: string[];
+}
+
+export function runHostConfigSetup<Opts extends object>(
+  patcher: HostConfigPatcher<Opts>,
+  hostOpts: Opts,
+  flags: RunHostSetupFlags,
+): RunHostSetupResult {
+  const out: string[] = [];
+  const configPath = flags.configPath ?? patcher.resolveConfigPath();
+
+  if (flags.print) {
+    const sample = patcher.computePatch({}, hostOpts);
+    out.push(`# Recommended ${patcher.hostName} config patch:`);
+    out.push(JSON.stringify(sample.next, null, 2));
+    return { exitCode: 0, output: out };
+  }
+
+  if (!existsSync(configPath)) {
+    out.push(`${patcher.hostName} config not found at: ${configPath}`);
+    out.push(`Initialize it first (e.g. \`openclaw doctor\` for OpenClaw), then re-run.`);
+    return { exitCode: 0, output: out };
+  }
+
+  let raw: string;
+  try {
+    raw = readFileSync(configPath, 'utf-8');
+  } catch (err: any) {
+    out.push(`Failed to read ${configPath}: ${err?.message ?? err}`);
+    return { exitCode: 1, output: out };
+  }
+
+  let current: unknown;
+  try {
+    current = JSON.parse(raw);
+  } catch (err: any) {
+    out.push(`Failed to parse JSON at ${configPath}: ${err?.message ?? err}`);
+    out.push(`Fix the JSON manually first; this tool does not edit malformed files.`);
+    return { exitCode: 1, output: out };
+  }
+
+  const { next, changes, warnings } = patcher.computePatch(current, hostOpts);
+
+  for (const w of warnings) out.push(`warning: ${w}`);
+
+  if (changes.length === 0) {
+    out.push(`${patcher.hostName} config already up to date at ${configPath}.`);
+    return { exitCode: 0, output: out };
+  }
+
+  if (!flags.yes) {
+    out.push(`Pending changes to ${configPath}:`);
+    for (const c of changes) out.push(`  - ${c}`);
+    out.push(``);
+    out.push(diffJson(current, next));
+    out.push(``);
+    out.push(`Dry-run only. Re-run with -y to apply.`);
+    return { exitCode: 2, output: out };
+  }
+
+  let backupPath: string | undefined;
+  if (flags.backup !== false) {
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    backupPath = `${configPath}.bak.${ts}`;
+    try {
+      copyFileSync(configPath, backupPath);
+    } catch (err: any) {
+      out.push(`Failed to back up ${configPath} → ${backupPath}: ${err?.message ?? err}`);
+      return { exitCode: 1, output: out };
+    }
+  }
+
+  const tmpPath = `${configPath}.tmp.${process.pid}`;
+  try {
+    const eol = raw.includes('\r\n') ? '\r\n' : '\n';
+    const serialized = JSON.stringify(next, null, 2).replace(/\n/g, eol) + eol;
+    writeFileSync(tmpPath, serialized, 'utf-8');
+    renameSync(tmpPath, configPath);
+  } catch (err: any) {
+    out.push(`Failed to write ${configPath}: ${err?.message ?? err}`);
+    return { exitCode: 1, output: out };
+  }
+
+  out.push(`Updated ${configPath}:`);
+  for (const c of changes) out.push(`  - ${c}`);
+  if (backupPath) out.push(`Backup: ${backupPath}`);
+  return { exitCode: 0, output: out };
+}
+
+/** Minimal line-level JSON diff for the dry-run preview. Self-contained, zero deps. */
+export function diffJson(before: unknown, after: unknown): string {
+  const a = JSON.stringify(before, null, 2).split('\n');
+  const b = JSON.stringify(after, null, 2).split('\n');
+  const aSet = new Set(a);
+  const bSet = new Set(b);
+  const lines: string[] = [];
+  const max = Math.max(a.length, b.length);
+  for (let i = 0; i < max; i++) {
+    const ax = a[i];
+    const bx = b[i];
+    if (ax === bx) {
+      lines.push(`  ${ax ?? ''}`);
+    } else {
+      if (ax !== undefined && !bSet.has(ax)) lines.push(`- ${ax}`);
+      if (bx !== undefined && !aSet.has(bx)) lines.push(`+ ${bx}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+/** Shared helper for hosts: add an entry to an array field, returning a new array (Set union). */
+export function unionArrayField(arr: unknown, entry: string): { next: string[]; added: boolean } | { warning: string } {
+  if (arr === undefined) return { next: [entry], added: true };
+  if (!Array.isArray(arr)) return { warning: `existing value is not an array, refusing to overwrite` };
+  if (arr.includes(entry)) return { next: arr.slice() as string[], added: false };
+  return { next: [...(arr as string[]), entry], added: true };
+}