@myclaw163/clawclaw-cli 0.6.67 → 0.6.69

package/src/commands/setup/openclaw.ts

@@ -1,147 +1,147 @@
-/**
- * `ccl setup openclaw` — install recommended OpenClaw config snippet.
- *
- * Pure function `computeOpenclawPatch` is exported for tests.
- * IO / diff / atomic write / backup is delegated to lib/host-config-patcher.ts.
- */
-
-import { Command } from 'commander';
-import { homedir } from 'os';
-import { join } from 'path';
-import {
-  runHostConfigSetup,
-  unionArrayField,
-  type HostPatchResult,
-} from '../../lib/host-config-patcher.js';
-
-export const PLUGIN_ID = 'clawclaw';
-
-export interface ComputeOpenclawPatchOpts {
-  skipPluginsAllow?: boolean;
-  skipToolsAllow?: boolean;
-}
-
-export function resolveOpenclawConfigPath(env: NodeJS.ProcessEnv = process.env): string {
-  const home = env.OPENCLAW_HOME?.trim();
-  if (home) return join(home, 'openclaw.json');
-  return join(homedir(), '.openclaw', 'openclaw.json');
-}
-
-/** Pure: compute the minimal additive patch to make `clawclaw` work under `coding` profile. */
-export function computeOpenclawPatch(current: unknown, opts: ComputeOpenclawPatchOpts): HostPatchResult {
-  const changes: string[] = [];
-  const warnings: string[] = [];
-  const cfg: Record<string, unknown> =
-    current !== null && typeof current === 'object' && !Array.isArray(current)
-      ? { ...(current as Record<string, unknown>) }
-      : {};
-
-  // ── plugins.allow + plugins.entries.clawclaw.enabled ──────────────────
-  if (!opts.skipPluginsAllow) {
-    const plugins: Record<string, unknown> =
-      cfg.plugins !== null && typeof cfg.plugins === 'object' && !Array.isArray(cfg.plugins)
-        ? { ...(cfg.plugins as Record<string, unknown>) }
-        : {};
-
-    const allowResult = unionArrayField(plugins.allow, PLUGIN_ID);
-    if ('warning' in allowResult) {
-      warnings.push(`plugins.allow ${allowResult.warning}`);
-    } else {
-      if (allowResult.added) {
-        if (plugins.allow === undefined) {
-          changes.push(`create plugins.allow with ["${PLUGIN_ID}"]`);
-        } else {
-          changes.push(`add "${PLUGIN_ID}" to plugins.allow`);
-        }
-      }
-      plugins.allow = allowResult.next;
-    }
-
-    const entries: Record<string, unknown> =
-      plugins.entries !== null && typeof plugins.entries === 'object' && !Array.isArray(plugins.entries)
-        ? { ...(plugins.entries as Record<string, unknown>) }
-        : {};
-    const existingEntry =
-      entries[PLUGIN_ID] !== null && typeof entries[PLUGIN_ID] === 'object' && !Array.isArray(entries[PLUGIN_ID])
-        ? { ...(entries[PLUGIN_ID] as Record<string, unknown>) }
-        : {};
-
-    if (existingEntry.enabled === false) {
-      warnings.push(
-        `plugins.entries.${PLUGIN_ID}.enabled is explicitly false; not flipping it on. Remove the line manually if you want it enabled.`,
-      );
-    } else if (existingEntry.enabled !== true) {
-      existingEntry.enabled = true;
-      entries[PLUGIN_ID] = existingEntry;
-      plugins.entries = entries;
-      changes.push(`set plugins.entries.${PLUGIN_ID}.enabled = true (equivalent to: openclaw plugins enable ${PLUGIN_ID})`);
-    }
-
-    cfg.plugins = plugins;
-  }
-
-  // ── tools.alsoAllow ────────────────────────────────────────────────────
-  if (!opts.skipToolsAllow) {
-    const tools: Record<string, unknown> =
-      cfg.tools !== null && typeof cfg.tools === 'object' && !Array.isArray(cfg.tools)
-        ? { ...(cfg.tools as Record<string, unknown>) }
-        : {};
-
-    const alsoAllowResult = unionArrayField(tools.alsoAllow, PLUGIN_ID);
-    if ('warning' in alsoAllowResult) {
-      warnings.push(`tools.alsoAllow ${alsoAllowResult.warning}`);
-    } else {
-      if (alsoAllowResult.added) {
-        if (tools.alsoAllow === undefined) {
-          changes.push(`create tools.alsoAllow with ["${PLUGIN_ID}"]`);
-        } else {
-          changes.push(`add "${PLUGIN_ID}" to tools.alsoAllow`);
-        }
-      }
-      tools.alsoAllow = alsoAllowResult.next;
-    }
-
-    cfg.tools = tools;
-  }
-
-  return { next: cfg, changes, warnings };
-}
-
-export function createSetupOpenclawSubcommand(): Command {
-  return new Command('openclaw')
-    .description('Install recommended OpenClaw config (plugins.allow + tools.alsoAllow) for the clawclaw plugin.')
-    .option('-y, --yes', 'Apply changes (default is dry-run with diff preview)')
-    .option('--print', 'Only print the recommended JSON patch; do not read or write files')
-    .option('--config <path>', 'Override openclaw.json path (default: $OPENCLAW_HOME/openclaw.json or ~/.openclaw/openclaw.json)')
-    .option('--skip-plugins-allow', "Do not touch plugins.allow / plugins.entries.clawclaw")
-    .option('--skip-tools-allow', "Do not touch tools.alsoAllow")
-    .option('--no-backup', 'Do not write a timestamped .bak.* before applying')
-    .action((opts: {
-      yes?: boolean;
-      print?: boolean;
-      config?: string;
-      skipPluginsAllow?: boolean;
-      skipToolsAllow?: boolean;
-      backup?: boolean;
-    }) => {
-      const result = runHostConfigSetup(
-        {
-          hostName: 'OpenClaw',
-          resolveConfigPath: () => resolveOpenclawConfigPath(),
-          computePatch: (current, hostOpts) => computeOpenclawPatch(current, hostOpts),
-        },
-        {
-          skipPluginsAllow: opts.skipPluginsAllow,
-          skipToolsAllow: opts.skipToolsAllow,
-        },
-        {
-          yes: opts.yes,
-          print: opts.print,
-          configPath: opts.config,
-          backup: opts.backup,
-        },
-      );
-      for (const line of result.output) console.log(line);
-      if (result.exitCode !== 0) process.exit(result.exitCode);
-    });
-}
+/**
+ * `ccl setup openclaw` — install recommended OpenClaw config snippet.
+ *
+ * Pure function `computeOpenclawPatch` is exported for tests.
+ * IO / diff / atomic write / backup is delegated to lib/host-config-patcher.ts.
+ */
+
+import { Command } from 'commander';
+import { homedir } from 'os';
+import { join } from 'path';
+import {
+  runHostConfigSetup,
+  unionArrayField,
+  type HostPatchResult,
+} from '../../lib/host-config-patcher.js';
+
+export const PLUGIN_ID = 'clawclaw';
+
+export interface ComputeOpenclawPatchOpts {
+  skipPluginsAllow?: boolean;
+  skipToolsAllow?: boolean;
+}
+
+export function resolveOpenclawConfigPath(env: NodeJS.ProcessEnv = process.env): string {
+  const home = env.OPENCLAW_HOME?.trim();
+  if (home) return join(home, 'openclaw.json');
+  return join(homedir(), '.openclaw', 'openclaw.json');
+}
+
+/** Pure: compute the minimal additive patch to make `clawclaw` work under `coding` profile. */
+export function computeOpenclawPatch(current: unknown, opts: ComputeOpenclawPatchOpts): HostPatchResult {
+  const changes: string[] = [];
+  const warnings: string[] = [];
+  const cfg: Record<string, unknown> =
+    current !== null && typeof current === 'object' && !Array.isArray(current)
+      ? { ...(current as Record<string, unknown>) }
+      : {};
+
+  // ── plugins.allow + plugins.entries.clawclaw.enabled ──────────────────
+  if (!opts.skipPluginsAllow) {
+    const plugins: Record<string, unknown> =
+      cfg.plugins !== null && typeof cfg.plugins === 'object' && !Array.isArray(cfg.plugins)
+        ? { ...(cfg.plugins as Record<string, unknown>) }
+        : {};
+
+    const allowResult = unionArrayField(plugins.allow, PLUGIN_ID);
+    if ('warning' in allowResult) {
+      warnings.push(`plugins.allow ${allowResult.warning}`);
+    } else {
+      if (allowResult.added) {
+        if (plugins.allow === undefined) {
+          changes.push(`create plugins.allow with ["${PLUGIN_ID}"]`);
+        } else {
+          changes.push(`add "${PLUGIN_ID}" to plugins.allow`);
+        }
+      }
+      plugins.allow = allowResult.next;
+    }
+
+    const entries: Record<string, unknown> =
+      plugins.entries !== null && typeof plugins.entries === 'object' && !Array.isArray(plugins.entries)
+        ? { ...(plugins.entries as Record<string, unknown>) }
+        : {};
+    const existingEntry =
+      entries[PLUGIN_ID] !== null && typeof entries[PLUGIN_ID] === 'object' && !Array.isArray(entries[PLUGIN_ID])
+        ? { ...(entries[PLUGIN_ID] as Record<string, unknown>) }
+        : {};
+
+    if (existingEntry.enabled === false) {
+      warnings.push(
+        `plugins.entries.${PLUGIN_ID}.enabled is explicitly false; not flipping it on. Remove the line manually if you want it enabled.`,
+      );
+    } else if (existingEntry.enabled !== true) {
+      existingEntry.enabled = true;
+      entries[PLUGIN_ID] = existingEntry;
+      plugins.entries = entries;
+      changes.push(`set plugins.entries.${PLUGIN_ID}.enabled = true (equivalent to: openclaw plugins enable ${PLUGIN_ID})`);
+    }
+
+    cfg.plugins = plugins;
+  }
+
+  // ── tools.alsoAllow ────────────────────────────────────────────────────
+  if (!opts.skipToolsAllow) {
+    const tools: Record<string, unknown> =
+      cfg.tools !== null && typeof cfg.tools === 'object' && !Array.isArray(cfg.tools)
+        ? { ...(cfg.tools as Record<string, unknown>) }
+        : {};
+
+    const alsoAllowResult = unionArrayField(tools.alsoAllow, PLUGIN_ID);
+    if ('warning' in alsoAllowResult) {
+      warnings.push(`tools.alsoAllow ${alsoAllowResult.warning}`);
+    } else {
+      if (alsoAllowResult.added) {
+        if (tools.alsoAllow === undefined) {
+          changes.push(`create tools.alsoAllow with ["${PLUGIN_ID}"]`);
+        } else {
+          changes.push(`add "${PLUGIN_ID}" to tools.alsoAllow`);
+        }
+      }
+      tools.alsoAllow = alsoAllowResult.next;
+    }
+
+    cfg.tools = tools;
+  }
+
+  return { next: cfg, changes, warnings };
+}
+
+export function createSetupOpenclawSubcommand(): Command {
+  return new Command('openclaw')
+    .description('Install recommended OpenClaw config (plugins.allow + tools.alsoAllow) for the clawclaw plugin.')
+    .option('-y, --yes', 'Apply changes (default is dry-run with diff preview)')
+    .option('--print', 'Only print the recommended JSON patch; do not read or write files')
+    .option('--config <path>', 'Override openclaw.json path (default: $OPENCLAW_HOME/openclaw.json or ~/.openclaw/openclaw.json)')
+    .option('--skip-plugins-allow', "Do not touch plugins.allow / plugins.entries.clawclaw")
+    .option('--skip-tools-allow', "Do not touch tools.alsoAllow")
+    .option('--no-backup', 'Do not write a timestamped .bak.* before applying')
+    .action((opts: {
+      yes?: boolean;
+      print?: boolean;
+      config?: string;
+      skipPluginsAllow?: boolean;
+      skipToolsAllow?: boolean;
+      backup?: boolean;
+    }) => {
+      const result = runHostConfigSetup(
+        {
+          hostName: 'OpenClaw',
+          resolveConfigPath: () => resolveOpenclawConfigPath(),
+          computePatch: (current, hostOpts) => computeOpenclawPatch(current, hostOpts),
+        },
+        {
+          skipPluginsAllow: opts.skipPluginsAllow,
+          skipToolsAllow: opts.skipToolsAllow,
+        },
+        {
+          yes: opts.yes,
+          print: opts.print,
+          configPath: opts.config,
+          backup: opts.backup,
+        },
+      );
+      for (const line of result.output) console.log(line);
+      if (result.exitCode !== 0) process.exit(result.exitCode);
+    });
+}

package/src/commands/watch.test.ts

@@ -21,9 +21,12 @@ describe('classifyEvent + NOTABLE_EVENT_TYPES', () => {
       'exile', 'speech_skipped', 'meeting_briefing',
       'speech', 'vote_phase_start', 'game_over',
       'speech_your_turn', 'vote_speech_phase_ended',
+      'crab_teammates', 'no_exile',
     ]) {
       expect(NOTABLE_EVENT_TYPES.has(t)).toBe(true);
     }
+    expect(NOTABLE_EVENT_TYPES.has('vote_cast')).toBe(false);
+    expect(NOTABLE_EVENT_TYPES.has('meeting_ended')).toBe(false);
   });
 
   it('derives NOTABLE_EVENT_TYPES from MONITOR_EVENT_CONFIG', () => {
@@ -36,7 +39,10 @@ describe('classifyEvent + NOTABLE_EVENT_TYPES', () => {
     expect(MONITOR_EVENT_CONFIG.killed.priority).toBe(99);
     expect(MONITOR_EVENT_CONFIG.speech.priority).toBe(50);
     expect(MONITOR_EVENT_CONFIG.vote_speech_phase_ended.priority).toBe(50);
+    expect(MONITOR_EVENT_CONFIG.crab_teammates.priority).toBe(50);
     expect(MONITOR_EVENT_CONFIG.vote_speech).toBeUndefined();
+    expect(MONITOR_EVENT_CONFIG.vote_cast).toBeUndefined();
+    expect(MONITOR_EVENT_CONFIG.meeting_ended).toBeUndefined();
   });
 
   it('classifyEvent returns notable=true for known types', () => {
@@ -64,6 +70,11 @@ describe('classifyEvent + NOTABLE_EVENT_TYPES', () => {
     expect(cls.notable).toBe(true);
   });
 
+  it('does not wake the monitor for private vote_cast or meeting_ended', () => {
+    expect(classifyEvent({ type: 'vote_cast', tick: 1, actor_name: 'me' }, 'me').notable).toBe(false);
+    expect(classifyEvent({ type: 'meeting_ended', tick: 2 }, 'me').notable).toBe(false);
+  });
+
   it('classifyEvent marks speech_skipped as notable', () => {
     expect(
       classifyEvent({ type: 'speech_skipped', tick: 1, actor_name: 'me' }, 'me').notable,

package/src/commands/watch.ts

@@ -65,6 +65,7 @@ export const MONITOR_EVENT_CONFIG: Record<string, MonitorEventConfig> = {
   vote_speech_phase_ended: { priority: 50 },
   death_speech: { priority: 50 },
   wandering_speech: { priority: 50 },
+  crab_teammates: { priority: 50 },
 
   meeting_briefing: { priority: 50 },
   speech: { priority: 50 },
@@ -72,8 +73,6 @@ export const MONITOR_EVENT_CONFIG: Record<string, MonitorEventConfig> = {
   speech_your_turn: { priority: 99 },
 
   vote_phase_start: { priority: 99 },
-  vote_cast: { priority: 50 },
-  meeting_ended: { priority: 50 },
 
   game_over: { priority: 50 },
   role_assigned: { priority: 50 },
@@ -149,7 +148,7 @@ interface RouteRule {
 const ROUTING_RULES: RouteRule[] = [
   { reason: 'speech_your_turn',    match: (t) => t.includes('speech_your_turn'),   nextStep: 'It is YOUR turn to speak. Submit `ccl do -s "<draft>"` immediately. Server skips you after 45s.' },
   { reason: 'role_assigned',        match: (t) => t.includes('role_assigned'),      nextStep: 'Tell user your role, faction, win condition, and first plan.' },
-  { reason: 'vote_cast',           match: (t) => t.includes('vote_cast'),          nextStep: 'A player just cast their vote. Read events[] to track who voted. No `ccl` action needed — cast your own vote immediately when vote phase starts.' },
+  { reason: 'crab_teammates',       match: (t) => t.includes('crab_teammates'),     nextStep: 'Crab teammate list is available. Keep teammate identities private, coordinate cover stories, and avoid voting or killing into them.' },
   { reason: 'match_start',         match: (t) => t.includes('match_start'),        nextStep: 'Matchmaking queue entered. The game runtime is live and the stream is attached. Chat with the user while waiting for allocation.' },
   { reason: 'match_waiting',       match: (t) => t.includes('match_waiting'),      nextStep: 'Still in queue (see `events[].waited_secs`). Keep chatting with the user; no tactical action required.' },
   { reason: 'match_timeout',       match: (t) => t.includes('match_timeout'),      nextStep: `Cumulative wait reached ${Math.round(DEFAULT_MATCH_TIMEOUT_MS / 60_000)} min (see \`events[].waited_secs\`). The stream will exit — discuss with the user: launch a fresh \`ccl game start\` to retry, or call it a session.` },

package/src/lib/auth.test.ts

@@ -39,6 +39,21 @@ describe('AuthStore TTS config', () => {
     expect(raw.profiles['lobster-1'].tts.defaultVoice).toBe('male-qn-qingse');
   });
 
+  it('clears cached game server URL when set to undefined', () => {
+    const store = new AuthStore(authFile);
+    store.addProfile({
+      agentName: 'lobster-1',
+      apiKey: 'claw_1',
+      serverUrl: 'https://example.com',
+      gameServerUrl: 'https://example.com/gs/old-game-server',
+    });
+
+    store.updateGameServerUrl(undefined);
+
+    const raw = JSON.parse(readFileSync(authFile, 'utf8'));
+    expect(raw.profiles['lobster-1'].gameServerUrl).toBeUndefined();
+  });
+
   it('migrates legacy neteaseTtsKey to each profile tts keys', () => {
     writeFileSync(authFile, JSON.stringify({
       activeProfile: 'lobster-1',

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 });
+  });
+});