@homeflare/alchemy 0.5.0 → 0.7.0

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

package/src/launchd/plist.ts

@@ -0,0 +1,156 @@
+/**
+ * An XML property list serializer — the subset launchd.plist(5) reads, and nothing else.
+ *
+ * ★ WHY NOT AN npm LIBRARY. Nothing in this workspace depends on one (checked 2026-09-21: no
+ *   `plist`, `xmlbuilder` or `@xmldom/xmldom` anywhere under node_modules), and the common one pulls
+ *   an XML DOM in for PARSING, which a provider that only RENDERS never does. The subset a launchd
+ *   job needs is five node types, so this is ~100 lines plus exhaustive tests (plist.test.ts), which
+ *   also round-trip every case through Apple's own `plutil` when the tests run on macOS.
+ *
+ * ⛔ THE OUTPUT MUST BE DETERMINISTIC. LaunchdJob diffs by the SHA-256 of these bytes, so two
+ *   renders of one declaration must be byte-identical: dict keys are sorted, indentation is fixed,
+ *   and nothing depends on insertion order. A non-deterministic render is a forever-`update`.
+ * ⚠️ AND A CHANGE TO THIS FILE'S OUTPUT RESTARTS EVERY JOB. A new header, indent or escape changes
+ *   every digest, so the next deploy after the kit upgrade updates — restarts — every declared
+ *   job at once. Treat any byte change here as a breaking change and say so in its changeset.
+ *
+ * ⛔ REFUSE, NEVER COERCE. `undefined`, `null`, a fraction, NaN, a class instance or a character XML
+ *   1.0 cannot carry is a thrown PlistError naming the path, not a silently dropped key. A dropped
+ *   `KeepAlive` is a daemon that never restarts, and nothing downstream would say why.
+ */
+
+/** Every value launchd reads. ⚠️ No `<real>`, `<date>` or `<data>`: no launchd key needs one. */
+export type PlistValue =
+  | string
+  | number
+  | boolean
+  | readonly PlistValue[]
+  | { readonly [key: string]: PlistValue };
+
+export type PlistDict = { readonly [key: string]: PlistValue };
+
+export class PlistError extends Error {
+  constructor(
+    readonly path: string,
+    detail: string,
+  ) {
+    super(`plist ${path === '' ? '(root)' : path}: ${detail}`);
+    this.name = 'PlistError';
+  }
+}
+
+const HEADER =
+  '<?xml version="1.0" encoding="UTF-8"?>\n' +
+  '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" ' +
+  '"http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n' +
+  '<plist version="1.0">\n';
+
+/** ⚠️ A cycle, or a runaway generator, would otherwise recurse until the stack dies. */
+const MAX_DEPTH = 32;
+
+/**
+ * ⛔ CHARACTERS XML 1.0 CANNOT CARRY AT ALL — not even escaped (XML 1.0 §2.2 `Char`). C0 controls
+ *   other than tab, LF and CR; U+FFFE / U+FFFF; and an unpaired surrogate, which has no UTF-8 form.
+ */
+// ★ The `u` flag makes a VALID surrogate pair one code point above U+FFFF, outside this class, so
+//   only an unpaired half matches the \uD800-\uDFFF range.
+// oxlint-disable-next-line no-control-regex -- matching control characters is the point
+const FORBIDDEN = /[\x00-\x08\x0B\x0C\x0E-\x1F\uD800-\uDFFF\uFFFE\uFFFF]/u;
+
+/**
+ * Escape text content.
+ * ⚠️ CR IS A CHARACTER REFERENCE, NOT A LITERAL. An XML parser normalises a literal CR (and CRLF)
+ *   to LF before the application sees it (XML 1.0 §2.11), so `a\r\nb` would come back as `a\nb` and
+ *   the argument launchd passes would differ from the one declared. `&#13;` survives normalisation.
+ */
+export const escapeText = (text: string, path: string): string => {
+  const bad = FORBIDDEN.exec(text);
+  if (bad !== null) {
+    const code = bad[0].codePointAt(0) ?? 0;
+    throw new PlistError(
+      path,
+      `U+${code.toString(16).toUpperCase().padStart(4, '0')} cannot appear in XML 1.0`,
+    );
+  }
+  return text
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('\r', '&#13;');
+};
+
+const isPlainObject = (value: object): boolean => {
+  const proto = Object.getPrototypeOf(value) as unknown;
+  return proto === Object.prototype || proto === null;
+};
+
+const renderValue = (value: unknown, path: string, depth: number, out: string[]): void => {
+  const pad = '\t'.repeat(depth);
+  if (depth > MAX_DEPTH) throw new PlistError(path, `nested deeper than ${String(MAX_DEPTH)}`);
+  if (typeof value === 'string') {
+    out.push(`${pad}<string>${escapeText(value, path)}</string>`);
+    return;
+  }
+  if (typeof value === 'boolean') {
+    out.push(`${pad}<${value ? 'true' : 'false'}/>`);
+    return;
+  }
+  if (typeof value === 'number') {
+    // ⛔ launchd reads every numeric key as an integer; 1.5 would be a silently different job.
+    if (!Number.isSafeInteger(value)) {
+      throw new PlistError(path, `${String(value)} is not a safe integer (no <real> support)`);
+    }
+    out.push(`${pad}<integer>${String(value === 0 ? 0 : value)}</integer>`);
+    return;
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      out.push(`${pad}<array/>`);
+      return;
+    }
+    out.push(`${pad}<array>`);
+    for (const [index, item] of (value as readonly unknown[]).entries()) {
+      renderValue(item, `${path}[${String(index)}]`, depth + 1, out);
+    }
+    out.push(`${pad}</array>`);
+    return;
+  }
+  if (typeof value === 'object' && value !== null && isPlainObject(value)) {
+    renderDict(value as Record<string, unknown>, path, depth, out);
+    return;
+  }
+  const kind = value === null ? 'null' : typeof value;
+  throw new PlistError(path, `${kind} has no plist form — omit the key instead`);
+};
+
+const renderDict = (
+  dict: Record<string, unknown>,
+  path: string,
+  depth: number,
+  out: string[],
+): void => {
+  const pad = '\t'.repeat(depth);
+  // ★ Code-unit order, not localeCompare: the same bytes on every machine and every locale.
+  const keys = Object.keys(dict).sort();
+  if (keys.length === 0) {
+    out.push(`${pad}<dict/>`);
+    return;
+  }
+  out.push(`${pad}<dict>`);
+  for (const key of keys) {
+    const child = path === '' ? key : `${path}.${key}`;
+    out.push(`${pad}\t<key>${escapeText(key, child)}</key>`);
+    renderValue(dict[key], child, depth + 1, out);
+  }
+  out.push(`${pad}</dict>`);
+};
+
+/** Render a top-level dict as a complete XML plist document, ending in a newline. */
+export const renderPlist = (dict: PlistDict): string => {
+  if (typeof dict !== 'object' || dict === null || Array.isArray(dict) || !isPlainObject(dict)) {
+    throw new PlistError('', 'the top level of a launchd plist must be a dict');
+  }
+  const out: string[] = [];
+  renderDict(dict as Record<string, unknown>, '', 0, out);
+  return `${HEADER}${out.join('\n')}\n</plist>\n`;
+};