@homeflare/alchemy 0.5.0 → 0.6.0

package/src/launchd/launchctl.ts

@@ -0,0 +1,188 @@
+/**
+ * The four `launchctl` subcommands LaunchdJob uses — print, print-disabled, bootstrap, bootout —
+ * over a HostRunner, plus the parsers for the two read-only ones.
+ *
+ * ★ MEASURED 2026-09-21 ON macOS 27.2 (read-only `print` / `print-disabled` only; nothing was
+ *   bootstrapped or booted out to write this):
+ *   - `print system/<unknown>` exits **113** with "Could not find service … in domain for system"
+ *     on stderr. 113 is therefore "not loaded", not an error.
+ *   - `print` of a loaded job is a `<target> = {` block. Its own fields sit one tab deep
+ *     (`\tstate = running`, `\tpid = 1219`, `\tlast exit code = 0` or `(never exited)`); nested
+ *     blocks (`resource coalition`, `semaphores`) repeat names like `state` two tabs deep.
+ *   - `print-disabled <domain>` lists `"label" => enabled|disabled`.
+ *   - reading needs no root: a uid-501 shell printed system-domain jobs.
+ *   - `print gui/<uid>/<label>` for a uid with NO LOGIN SESSION exits **112** with "Could not find
+ *     domain for user gui: <uid>" (and so does `print-disabled gui/<uid>`); a malformed target is
+ *     64, a missing service in a live gui domain is 113. So 112 + that text is "the domain does
+ *     not exist", which means the job cannot be loaded — not an error for a read or a delete.
+ * ⚠️ REASONED, NOT MEASURED: bootstrap/bootout exit codes. nix-darwin's own activation script on the
+ *   same host notes "`bootout` on an already-absent job is a no-op that returns non-zero", which is
+ *   why bootout here is always preceded by a print and followed by a poll, never trusted alone.
+ * ⛔ NEVER PUT `print` STDOUT IN AN ERROR. It contains the job's whole environment.
+ */
+import type { HostRunner } from './runner.ts';
+
+export const LAUNCHCTL = '/bin/launchctl';
+/** `launchctl print` of an unknown service — measured, see above. */
+export const NOT_FOUND = 113;
+/** `launchctl print` into a gui domain with no login session — measured, see above. */
+export const NO_DOMAIN = 112;
+const NO_DOMAIN_TEXT = 'Could not find domain';
+
+export class LaunchctlError extends Error {
+  constructor(command: string, exitCode: number, stderr: string) {
+    super(`launchctl ${command} -> ${String(exitCode)}: ${stderr.trim().slice(0, 300)}`);
+    this.name = 'LaunchctlError';
+  }
+}
+
+export type ServiceStatus = {
+  readonly loaded: boolean;
+  /** The domain itself is absent (a gui/<uid> with no login session). Implies `loaded: false`. */
+  readonly domainMissing?: true;
+  readonly state?: string;
+  readonly pid?: number;
+  readonly lastExitCode?: number;
+};
+
+/**
+ * The job block's own `key = value` lines, ignoring nested blocks.
+ * ⚠️ A multi-line ProgramArguments entry is printed raw inside `arguments = {`, so a close is only
+ *   accepted when its indentation matches the open. An argument that itself contains a line of
+ *   exactly one tab and `}` would still desynchronise this; no real job has one.
+ */
+export const printFields = (stdout: string): Map<string, string> => {
+  const fields = new Map<string, string>();
+  const closers: string[] = [];
+  for (const line of stdout.split('\n')) {
+    if (closers.length === 0) {
+      if (fields.size === 0 && line.endsWith(' = {')) closers.push('}');
+      continue;
+    }
+    if (line === closers[closers.length - 1]) {
+      closers.pop();
+      continue;
+    }
+    const opened = /^(\t+)\S.* = \{$/.exec(line);
+    if (opened?.[1] !== undefined && opened[1].length === closers.length) {
+      closers.push(`${opened[1]}}`);
+      continue;
+    }
+    const field = closers.length === 1 ? /^\t([a-z][a-z ]*[a-z]) = (.*)$/.exec(line) : null;
+    if (field?.[1] !== undefined && field[2] !== undefined && !fields.has(field[1])) {
+      fields.set(field[1], field[2]);
+    }
+  }
+  return fields;
+};
+
+const leadingInt = (text: string | undefined): number | undefined => {
+  const match = text === undefined ? null : /^(-?\d+)/.exec(text);
+  return match?.[1] === undefined ? undefined : Number(match[1]);
+};
+
+export const parsePrint = (stdout: string): ServiceStatus => {
+  const fields = printFields(stdout);
+  const state = fields.get('state');
+  const pid = leadingInt(fields.get('pid'));
+  // "(never exited)" parses to undefined; "78: EX_CONFIG" to 78.
+  const lastExitCode = leadingInt(fields.get('last exit code'));
+  return {
+    loaded: true,
+    ...(state === undefined ? {} : { state }),
+    ...(pid === undefined ? {} : { pid }),
+    ...(lastExitCode === undefined ? {} : { lastExitCode }),
+  };
+};
+
+/** Labels `print-disabled` reports as disabled. Older releases printed `=> true` for disabled. */
+export const parseDisabled = (stdout: string): Set<string> => {
+  const disabled = new Set<string>();
+  for (const match of stdout.matchAll(/^\s*"([^"]+)" => (\w+)\s*$/gm)) {
+    if (match[1] !== undefined && (match[2] === 'disabled' || match[2] === 'true')) {
+      disabled.add(match[1]);
+    }
+  }
+  return disabled;
+};
+
+export const printService = async (runner: HostRunner, target: string): Promise<ServiceStatus> => {
+  const result = await runner.exec([LAUNCHCTL, 'print', target]);
+  if (result.exitCode === NOT_FOUND) return { loaded: false };
+  // ⚠️ Without this, deleting an agent while its user is logged out fails on the read, and the
+  //   plist stays in LaunchAgents — where launchd loads it again at that user's next login.
+  if (result.exitCode === NO_DOMAIN && result.stderr.includes(NO_DOMAIN_TEXT)) {
+    return { domainMissing: true, loaded: false };
+  }
+  if (result.exitCode !== 0)
+    throw new LaunchctlError(`print ${target}`, result.exitCode, result.stderr);
+  return parsePrint(result.stdout);
+};
+
+export const isDisabled = async (
+  runner: HostRunner,
+  domain: string,
+  label: string,
+): Promise<boolean> => {
+  const result = await runner.exec([LAUNCHCTL, 'print-disabled', domain]);
+  if (result.exitCode !== 0) {
+    throw new LaunchctlError(`print-disabled ${domain}`, result.exitCode, result.stderr);
+  }
+  return parseDisabled(result.stdout).has(label);
+};
+
+export const bootstrap = async (
+  runner: HostRunner,
+  domain: string,
+  plistPath: string,
+): Promise<void> => {
+  const result = await runner.exec([LAUNCHCTL, 'bootstrap', domain, plistPath]);
+  if (result.exitCode !== 0) {
+    throw new LaunchctlError(`bootstrap ${domain} ${plistPath}`, result.exitCode, result.stderr);
+  }
+};
+
+/**
+ * Poll `print` until the service is gone. ⚠️ bootout can return before launchd lets go of it.
+ * ★ 30 s, because a job gets SIGTERM and then its ExitTimeOut before SIGKILL: launchd.plist(5)
+ *   documents a 20 s default (a macOS 27.2 `print` showed `exit timeout = 5` for a job that sets
+ *   none). Giving up sooner would fail a deploy over a job that was, correctly, still exiting.
+ */
+export const waitUnloaded = async (
+  runner: HostRunner,
+  target: string,
+  attempts = 120,
+  intervalMs = 250,
+): Promise<void> => {
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    if (!(await printService(runner, target)).loaded) return;
+    await runner.sleep(intervalMs);
+  }
+  throw new Error(
+    `${target} is still loaded ${String((attempts * intervalMs) / 1000)}s after bootout`,
+  );
+};
+
+/** Boot a service out if it is loaded, and wait until launchd has let go. Idempotent. */
+export const bootoutIfLoaded = async (runner: HostRunner, target: string): Promise<void> => {
+  if (!(await printService(runner, target)).loaded) return;
+  const result = await runner.exec([LAUNCHCTL, 'bootout', target]);
+  /**
+   * ⚠️ A non-zero bootout is only an error if the service is STILL there after the wait (see
+   *   header) — so wait FIRST, then judge. A job slower to exit than launchctl's own wait is widely
+   *   reported to fail bootout with `36: Operation now in progress` (EINPROGRESS) while it is
+   *   still going away; REASONED from those reports, not measured here. Judging on an immediate
+   *   print would fail the deploy with the new plist written and the old job already exiting —
+   *   the job ends up down either way, and the error would blame the wrong step.
+   */
+  try {
+    await waitUnloaded(runner, target);
+  } catch (cause) {
+    if (result.exitCode === 0) throw cause;
+    throw new LaunchctlError(
+      `bootout ${target}`,
+      result.exitCode,
+      `${result.stderr.trim()} (and still loaded after waiting)`,
+    );
+  }
+};

package/src/launchd/local-runner.test.ts

@@ -0,0 +1,125 @@
+/**
+ * The real runner, confined to a fresh temp directory. It never runs launchctl and never writes
+ * outside `mkdtemp`; the only programs it spawns are echo/false and a read-only user lookup.
+ */
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtemp, readdir, rm, stat, symlink, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { localRunner } from './local-runner.ts';
+
+const runner = localRunner();
+let dir = '';
+
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'hf-local-runner-'));
+});
+afterEach(async () => {
+  await rm(dir, { force: true, recursive: true });
+});
+
+const bytes = (text: string) => new TextEncoder().encode(text);
+
+describe('writeFileAtomic', () => {
+  test('writes the bytes with the declared mode and leaves no temp file behind', async () => {
+    const path = join(dir, 'a.conf');
+    await runner.writeFileAtomic(path, bytes('one\n'), { mode: 0o640 });
+    expect(await Bun.file(path).text()).toBe('one\n');
+    expect((await stat(path)).mode & 0o7777).toBe(0o640);
+    expect(await readdir(dir)).toEqual(['a.conf']);
+  });
+
+  test('replaces by rename — a new inode, never an in-place rewrite', async () => {
+    const path = join(dir, 'a.conf');
+    await runner.writeFileAtomic(path, bytes('one\n'), { mode: 0o644 });
+    const before = (await stat(path)).ino;
+    await runner.writeFileAtomic(path, bytes('two\n'), { mode: 0o644 });
+    expect(await Bun.file(path).text()).toBe('two\n');
+    expect((await stat(path)).ino).not.toBe(before);
+  });
+
+  test('a missing parent directory fails and creates nothing', async () => {
+    await expect(
+      runner.writeFileAtomic(join(dir, 'no/such/a'), bytes('x'), { mode: 0o644 }),
+    ).rejects.toThrow();
+    expect(await readdir(dir)).toEqual([]);
+  });
+
+  test.skipIf(process.geteuid?.() === 0)('a refused chown cleans up its temp file', async () => {
+    const path = join(dir, 'owned');
+    await expect(
+      runner.writeFileAtomic(path, bytes('x'), { mode: 0o644, uid: 0 }),
+    ).rejects.toThrow();
+    expect(await readdir(dir)).toEqual([]);
+  });
+
+  test('chowning to yourself is allowed, and is how an agent plist is written', async () => {
+    const path = join(dir, 'mine');
+    await runner.writeFileAtomic(path, bytes('x'), { mode: 0o600, uid: runner.effectiveUid() });
+    expect((await stat(path)).uid).toBe(runner.effectiveUid());
+  });
+});
+
+describe('read, stat, remove', () => {
+  test('absent paths read as undefined, including under a file', async () => {
+    expect(await runner.readFile(join(dir, 'none'))).toBeUndefined();
+    expect(await runner.stat(join(dir, 'none'))).toBeUndefined();
+    await writeFile(join(dir, 'f'), 'x');
+    expect(await runner.stat(join(dir, 'f', 'under'))).toBeUndefined();
+  });
+
+  test('stat is lstat: a symlink is reported as one, and mode carries no type bits', async () => {
+    await writeFile(join(dir, 'target'), 'x', { mode: 0o600 });
+    await symlink(join(dir, 'target'), join(dir, 'link'));
+    expect((await runner.stat(join(dir, 'link')))?.kind).toBe('symlink');
+    expect(await runner.stat(join(dir, 'target'))).toMatchObject({
+      kind: 'file',
+      mode: 0o600,
+      size: 1,
+    });
+    expect((await runner.stat(dir))?.kind).toBe('directory');
+  });
+
+  test('readFile returns the bytes; removeFile is idempotent', async () => {
+    await writeFile(join(dir, 'f'), 'hello');
+    expect(new TextDecoder().decode(await runner.readFile(join(dir, 'f')))).toBe('hello');
+    await runner.removeFile(join(dir, 'f'));
+    await runner.removeFile(join(dir, 'f'));
+    expect(await readdir(dir)).toEqual([]);
+  });
+});
+
+describe('exec', () => {
+  test('argv is passed verbatim — no shell ever sees it', async () => {
+    const result = await runner.exec(['/bin/echo', '$HOME;`id`|*']);
+    expect(result).toEqual({ exitCode: 0, stderr: '', stdout: '$HOME;`id`|*\n' });
+  });
+
+  test('a non-zero exit is a result, not a throw', async () => {
+    expect((await runner.exec(['/usr/bin/false'])).exitCode).not.toBe(0);
+  });
+
+  test('a program that does not exist rejects with its name', async () => {
+    await expect(runner.exec([join(dir, 'missing')])).rejects.toThrow('missing');
+    await expect(runner.exec([])).rejects.toThrow('empty argv');
+  });
+
+  test('never privileged, and reports the real euid', () => {
+    expect(runner.privileged).toBe(false);
+    expect(runner.effectiveUid()).toBe(process.geteuid?.() ?? -1);
+  });
+});
+
+describe.skipIf(!['darwin', 'linux'].includes(process.platform))('lookups (read-only)', () => {
+  test('the current user resolves by uid, with a home directory', async () => {
+    const uid = process.getuid?.() ?? -1;
+    const user = await runner.lookupUser(String(uid));
+    expect(user?.uid).toBe(uid);
+    expect(user?.home.startsWith('/')).toBe(true);
+  });
+
+  test('an unknown user and group are undefined, not errors', async () => {
+    expect(await runner.lookupUser('hf-no-such-user-xyz')).toBeUndefined();
+    expect(await runner.lookupGroup('hf-no-such-group-xyz')).toBeUndefined();
+  });
+});

package/src/launchd/local-runner.ts

@@ -0,0 +1,143 @@
+/**
+ * The real HostRunner: this process, this machine, this uid.
+ *
+ * ★ node:fs AND node:child_process, NOT Bun APIs. An Alchemy stack usually runs under bun, but
+ *   the published dist also loads under node (the package's smoke test and the kit's AGENTS.md:
+ *   consumers run dist/, not src/), and both runtimes implement these modules.
+ * ⛔ NO ELEVATION, EVER. `privileged` is false; a system-domain write succeeds only when the whole
+ *   deploy was started as root. See the ⛔ on HostRunner.privileged for why nothing here calls sudo.
+ * ⛔ NO SHELL. `exec` spawns argv directly, so a label, path or argument can never be re-parsed
+ *   as shell syntax.
+ */
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { lstat, open, readFile, rename, unlink } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { groupQuery, parseGroup, parseUser, userQuery } from './host-lookup.ts';
+import type { ExecResult, FileStat, HostRunner, WriteOptions } from './runner.ts';
+
+export type LocalRunnerOptions = {
+  /** Kill a spawned program after this long. @default 120_000 */
+  readonly execTimeoutMs?: number;
+};
+
+const code = (cause: unknown): string | undefined =>
+  typeof cause === 'object' && cause !== null && 'code' in cause
+    ? String((cause as { code: unknown }).code)
+    : undefined;
+
+/** ENOENT and ENOTDIR both mean "nothing is at this path". */
+const absent = (cause: unknown): boolean => code(cause) === 'ENOENT' || code(cause) === 'ENOTDIR';
+
+const run = (argv: readonly string[], timeoutMs: number): Promise<ExecResult> =>
+  new Promise((resolve, reject) => {
+    const [program, ...args] = argv;
+    if (program === undefined) {
+      reject(new Error('exec: empty argv'));
+      return;
+    }
+    const child = spawn(program, args, {
+      shell: false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: timeoutMs,
+    });
+    const out: Buffer[] = [];
+    const err: Buffer[] = [];
+    child.stdout.on('data', (chunk: Buffer) => out.push(chunk));
+    child.stderr.on('data', (chunk: Buffer) => err.push(chunk));
+    child.on('error', (cause) => {
+      reject(new Error(`exec ${program}: ${cause.message}`));
+    });
+    child.on('close', (exitCode, signal) => {
+      const stderr = Buffer.concat(err).toString('utf8');
+      resolve({
+        // ⚠️ A signal (including our own timeout) has no exit code; -1 keeps it a failure.
+        exitCode: exitCode ?? -1,
+        stderr: signal === null ? stderr : `${stderr}\n(killed by ${signal})`.trim(),
+        stdout: Buffer.concat(out).toString('utf8'),
+      });
+    });
+  });
+
+const kindOf = (stats: Awaited<ReturnType<typeof lstat>>): FileStat['kind'] => {
+  if (stats.isSymbolicLink()) return 'symlink';
+  if (stats.isFile()) return 'file';
+  if (stats.isDirectory()) return 'directory';
+  return 'other';
+};
+
+const writeAtomic = async (path: string, bytes: Uint8Array, options: WriteOptions) => {
+  // ★ Same directory as the target, so rename(2) never crosses a filesystem (which would EXDEV).
+  const temp = join(dirname(path), `.${basename(path)}.${randomBytes(6).toString('hex')}.tmp`);
+  // ⛔ 'wx' = O_CREAT|O_EXCL, and 0600 until the final mode: the temp file is never readable by
+  //   anyone else in the moment before its mode is set, and never follows a planted symlink.
+  const handle = await open(temp, 'wx', 0o600);
+  try {
+    try {
+      await handle.writeFile(bytes);
+      // ⚠️ chown BEFORE chmod: a chown by root clears setuid/setgid bits, so the other order
+      //   would silently drop a declared 4755.
+      if (options.uid !== undefined || options.gid !== undefined) {
+        await handle.chown(options.uid ?? -1, options.gid ?? -1);
+      }
+      await handle.chmod(options.mode);
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await rename(temp, path);
+  } catch (cause) {
+    await unlink(temp).catch(() => undefined);
+    throw cause;
+  }
+};
+
+export const localRunner = (options: LocalRunnerOptions = {}): HostRunner => {
+  const timeoutMs = options.execTimeoutMs ?? 120_000;
+  const platform = process.platform;
+  return {
+    effectiveUid: () => process.geteuid?.() ?? -1,
+    exec: (argv) => run(argv, timeoutMs),
+    lookupGroup: async (nameOrId) => {
+      const result = await run(groupQuery(platform, nameOrId), timeoutMs);
+      return result.exitCode === 0 ? parseGroup(platform, result.stdout) : undefined;
+    },
+    lookupUser: async (nameOrId) => {
+      const result = await run(userQuery(platform, nameOrId), timeoutMs);
+      return result.exitCode === 0 ? parseUser(platform, result.stdout) : undefined;
+    },
+    privileged: false,
+    readFile: async (path) => {
+      try {
+        return new Uint8Array(await readFile(path));
+      } catch (cause) {
+        if (absent(cause)) return undefined;
+        throw cause;
+      }
+    },
+    removeFile: async (path) => {
+      try {
+        await unlink(path);
+      } catch (cause) {
+        if (!absent(cause)) throw cause;
+      }
+    },
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    stat: async (path) => {
+      try {
+        const stats = await lstat(path);
+        return {
+          gid: stats.gid,
+          kind: kindOf(stats),
+          mode: stats.mode & 0o7777,
+          size: stats.size,
+          uid: stats.uid,
+        };
+      } catch (cause) {
+        if (absent(cause)) return undefined;
+        throw cause;
+      }
+    },
+    writeFileAtomic: writeAtomic,
+  };
+};

package/src/launchd/plist.test.ts

@@ -0,0 +1,186 @@
+/**
+ * The plist serializer, case by case — and, on macOS, every case round-tripped through Apple's own
+ * `plutil`, so "valid plist" is Apple's verdict rather than this file's opinion.
+ *
+ * ⚠️ plutil only READS here: it converts a file in a fresh temp directory to JSON on stdout.
+ */
+import { describe, expect, test } from 'bun:test';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { type PlistDict, PlistError, escapeText, renderPlist } from './plist.ts';
+
+const body = (dict: PlistDict) => {
+  const text = renderPlist(dict);
+  return text.slice(text.indexOf('<dict'), text.lastIndexOf('</plist>')).trimEnd();
+};
+
+describe('renderPlist', () => {
+  test('a complete document: XML declaration, Apple DOCTYPE, plist 1.0, trailing newline', () => {
+    const text = renderPlist({ Label: 'com.example.job' });
+    expect(text.startsWith('<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC')).toBe(
+      true,
+    );
+    expect(text).toContain(
+      '<plist version="1.0">\n<dict>\n\t<key>Label</key>\n\t<string>com.example.job</string>\n</dict>\n</plist>\n',
+    );
+  });
+
+  test('strings, integers and booleans', () => {
+    expect(body({ a: 'x', b: 42, c: -7, d: 0, e: true, f: false })).toBe(
+      [
+        '<dict>',
+        '\t<key>a</key>',
+        '\t<string>x</string>',
+        '\t<key>b</key>',
+        '\t<integer>42</integer>',
+        '\t<key>c</key>',
+        '\t<integer>-7</integer>',
+        '\t<key>d</key>',
+        '\t<integer>0</integer>',
+        '\t<key>e</key>',
+        '\t<true/>',
+        '\t<key>f</key>',
+        '\t<false/>',
+        '</dict>',
+      ].join('\n'),
+    );
+  });
+
+  test('negative zero renders as 0', () => {
+    expect(body({ z: -0 })).toContain('<integer>0</integer>');
+  });
+
+  test('arrays and nested dicts indent one tab per level', () => {
+    expect(body({ args: ['/bin/sh', '-c'], keep: { SuccessfulExit: false } })).toBe(
+      [
+        '<dict>',
+        '\t<key>args</key>',
+        '\t<array>',
+        '\t\t<string>/bin/sh</string>',
+        '\t\t<string>-c</string>',
+        '\t</array>',
+        '\t<key>keep</key>',
+        '\t<dict>',
+        '\t\t<key>SuccessfulExit</key>',
+        '\t\t<false/>',
+        '\t</dict>',
+        '</dict>',
+      ].join('\n'),
+    );
+  });
+
+  test('empty containers self-close', () => {
+    expect(body({ a: [], d: {} })).toBe(
+      '<dict>\n\t<key>a</key>\n\t<array/>\n\t<key>d</key>\n\t<dict/>\n</dict>',
+    );
+    expect(body({})).toBe('<dict/>');
+  });
+
+  test('dicts in arrays (StartCalendarInterval)', () => {
+    expect(body({ s: [{ Hour: 3 }, { Minute: 5 }] })).toContain(
+      '\t<array>\n\t\t<dict>\n\t\t\t<key>Hour</key>\n\t\t\t<integer>3</integer>\n\t\t</dict>',
+    );
+  });
+
+  test('keys are sorted, so insertion order never changes the bytes', () => {
+    expect(renderPlist({ b: 1, a: 2, C: 3 })).toBe(renderPlist({ C: 3, a: 2, b: 1 }));
+    expect(body({ b: 1, a: 2, C: 3 }).indexOf('<key>C</key>')).toBeLessThan(
+      body({ b: 1, a: 2, C: 3 }).indexOf('<key>a</key>'),
+    );
+  });
+});
+
+describe('escaping', () => {
+  test('&, < and > are escaped in values and keys', () => {
+    expect(body({ 'a&b': '<x> & "y" \'z\'' })).toContain(
+      '<key>a&amp;b</key>\n\t<string>&lt;x&gt; &amp; "y" \'z\'</string>',
+    );
+  });
+
+  test('a would-be CDATA end or entity is inert', () => {
+    expect(escapeText(']]>&amp;', 'p')).toBe(']]&gt;&amp;amp;');
+  });
+
+  test('CR becomes a character reference; tab and LF stay literal', () => {
+    expect(escapeText('a\r\nb\tc', 'p')).toBe('a&#13;\nb\tc');
+  });
+
+  test('non-ASCII and astral characters pass through as UTF-8', () => {
+    expect(escapeText('café — 日本 \u{1F600}', 'p')).toBe('café — 日本 \u{1F600}');
+  });
+
+  test.each([
+    ['NUL', '\x00'],
+    ['BEL', '\x07'],
+    ['VT', '\x0B'],
+    ['ESC', '\x1B'],
+    ['U+FFFE', String.fromCharCode(0xfffe)],
+    ['U+FFFF', String.fromCharCode(0xffff)],
+    ['a lone high surrogate', String.fromCharCode(0xd83d)],
+    ['a lone low surrogate', `a${String.fromCharCode(0xde00)}`],
+  ])('%s is refused with the path, not dropped', (_name, bad) => {
+    expect(() => renderPlist({ outer: { inner: [`ok${bad}`] } })).toThrow(PlistError);
+    expect(() => renderPlist({ outer: { inner: [`ok${bad}`] } })).toThrow('outer.inner[0]');
+  });
+});
+
+describe('refusals', () => {
+  test.each([
+    ['a fraction', 1.5],
+    ['NaN', Number.NaN],
+    ['Infinity', Number.POSITIVE_INFINITY],
+    ['an unsafe integer', 2 ** 60],
+    ['undefined', undefined],
+    ['null', null],
+    ['a Date', new Date(0)],
+    ['a function', () => 1],
+    ['a bigint', 1n],
+  ])('%s', (_name, value) => {
+    expect(() => renderPlist({ k: value } as unknown as PlistDict)).toThrow(PlistError);
+  });
+
+  test('a non-dict top level', () => {
+    expect(() => renderPlist([] as unknown as PlistDict)).toThrow('top level');
+  });
+
+  test('a cycle stops at the depth cap instead of overflowing the stack', () => {
+    const loop: Record<string, unknown> = {};
+    loop['self'] = loop;
+    expect(() => renderPlist(loop as PlistDict)).toThrow('nested deeper');
+  });
+});
+
+const plutil = '/usr/bin/plutil';
+const onMac = process.platform === 'darwin' && (await Bun.file(plutil).exists());
+
+describe.skipIf(!onMac)("Apple's plutil reads it back identically", () => {
+  const cases: Record<string, PlistDict> = {
+    scalars: { s: 'x', i: 42, n: -7, t: true, f: false },
+    nested: { a: ['/bin/sh', '-c', 'exec "$prog"'], d: { SuccessfulExit: false }, e: [], o: {} },
+    special: { 'a&b<c>': '<&> "q" \'a\' ]]> tab\there\nnewline\r\ncrlf café \u{1F600}' },
+    launchd: {
+      Label: 'com.example.job',
+      ProgramArguments: ['/usr/bin/true'],
+      StartCalendarInterval: [{ Hour: 3, Minute: 30 }, { Weekday: 0 }],
+      KeepAlive: { SuccessfulExit: false },
+    },
+  };
+
+  test.each(Object.entries(cases))('%s', async (_name, dict) => {
+    const dir = await mkdtemp(join(tmpdir(), 'hf-plist-'));
+    try {
+      const file = join(dir, 'case.plist');
+      await writeFile(file, renderPlist(dict));
+      const proc = Bun.spawn([plutil, '-convert', 'json', '-o', '-', file], {
+        stderr: 'pipe',
+        stdout: 'pipe',
+      });
+      const out = await new Response(proc.stdout).text();
+      expect(await proc.exited).toBe(0);
+      expect(JSON.parse(out)).toEqual(dict);
+    } finally {
+      await rm(dir, { force: true, recursive: true });
+    }
+  });
+});