@homeflare/alchemy 0.5.0 → 0.6.0

package/src/launchd/host-file.ts

@@ -0,0 +1,64 @@
+/**
+ * `Host.File` — one text file on the host, declared: content, mode, owner, group.
+ *
+ * - create / update — atomic write (temp file in the same directory, mode and owner set, rename),
+ *   skipped when the file already matches; then read back and compared.
+ * - read — lstat plus the SHA-256 of the bytes.
+ * - diff — declared SHA-256 against the stored and on-disk digest, plus mode and owner.
+ * - replace — only when `path` changes; create-before-delete.
+ * - delete — removes the file.
+ *
+ * ⛔ NEVER A SECRET — see host-file-form.ts. Secret files stay rendered by openbao-agent.
+ * ⚠️ NOTHING IS ADOPTED WITHOUT `--adopt`: a file already at the path reads as `Unowned`.
+ * ★ IT LIVES IN THE launchd SUBPATH because the two travel together: a Mac host stack declares a
+ *   daemon's config file and the daemon that reads it, through the same HostRunner.
+ */
+import { Resource } from 'alchemy';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { isResolved } from 'alchemy/Diff';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { lift, resolvedString } from './host-effect.ts';
+import type { HostFileAttributes, HostFileProps } from './host-file-form.ts';
+import { deleteFile, diffFile, readFileAttributes, reconcileFile } from './host-file-lifecycle.ts';
+import { HostRunnerService } from './runner.ts';
+
+export type { HostFileAttributes, HostFileProps } from './host-file-form.ts';
+
+export interface HostFile extends Resource<'Host.File', HostFileProps, HostFileAttributes> {}
+
+export const HostFile = Resource<HostFile>('Host.File');
+
+export const HostFileProvider = () =>
+  Provider.effect(
+    HostFile,
+    Effect.gen(function* () {
+      const runner = yield* HostRunnerService;
+      return HostFile.Provider.of({
+        list: () => Effect.succeed([]),
+
+        read: ({ olds, output }) =>
+          lift(async () => {
+            const found = await readFileAttributes(runner, olds.path);
+            if (found === undefined) return undefined;
+            return output === undefined ? Unowned(found) : found;
+          }),
+
+        diff: ({ news, output }) => {
+          if (output === undefined) return Effect.succeed(undefined);
+          if (isResolved(news)) return lift(() => diffFile(runner, news, output));
+          // ⛔ A new path is a replace even while `content` is unresolved (an Output templated in):
+          //   the engine's default would be an update, which writes the new path and never
+          //   removes the old one. reconcileFile also defends, for a path that is an Output.
+          const path = resolvedString(news, 'path');
+          return Effect.succeed(
+            path !== undefined && path !== output.path ? { action: 'replace' as const } : undefined,
+          );
+        },
+
+        reconcile: ({ news, output }) => lift(() => reconcileFile(runner, news, output)),
+
+        delete: ({ output }) => lift(() => deleteFile(runner, output)),
+      });
+    }),
+  );

package/src/launchd/host-lookup.test.ts

@@ -0,0 +1,92 @@
+/**
+ * The lookup parsers against the dscacheutil shape measured on macOS 27.2 and getent's documented
+ * one — pure strings, nothing runs.
+ */
+import { describe, expect, test } from 'bun:test';
+import { groupQuery, parseGroup, parseUser, userQuery } from './host-lookup.ts';
+
+const DSCACHE_USER = [
+  'name: someone',
+  'password: ********',
+  'uid: 501',
+  'gid: 20',
+  'dir: /Users/someone',
+  'shell: /bin/zsh',
+  'gecos: Some One',
+  '',
+  'name: second',
+  'uid: 502',
+  'gid: 20',
+  'dir: /Users/second',
+  '',
+].join('\n');
+
+describe('queries', () => {
+  test('macOS asks dscacheutil by uid or by name; elsewhere getent', () => {
+    expect(userQuery('darwin', '501')).toEqual([
+      '/usr/bin/dscacheutil',
+      '-q',
+      'user',
+      '-a',
+      'uid',
+      '501',
+    ]);
+    expect(userQuery('darwin', 'someone')).toEqual([
+      '/usr/bin/dscacheutil',
+      '-q',
+      'user',
+      '-a',
+      'name',
+      'someone',
+    ]);
+    expect(groupQuery('darwin', 'wheel')).toEqual([
+      '/usr/bin/dscacheutil',
+      '-q',
+      'group',
+      '-a',
+      'name',
+      'wheel',
+    ]);
+    expect(groupQuery('darwin', '0')).toEqual([
+      '/usr/bin/dscacheutil',
+      '-q',
+      'group',
+      '-a',
+      'gid',
+      '0',
+    ]);
+    expect(userQuery('linux', 'someone')).toEqual(['getent', 'passwd', 'someone']);
+    expect(groupQuery('linux', 'wheel')).toEqual(['getent', 'group', 'wheel']);
+  });
+});
+
+describe('parseUser', () => {
+  test('dscacheutil: the first record only, and never the password field', () => {
+    const user = parseUser('darwin', DSCACHE_USER);
+    expect(user).toEqual({ gid: 20, home: '/Users/someone', uid: 501 });
+    expect(JSON.stringify(user)).not.toContain('*');
+  });
+
+  test('dscacheutil: an unknown user prints nothing (measured) and parses to undefined', () => {
+    expect(parseUser('darwin', '')).toBeUndefined();
+    expect(parseUser('darwin', 'name: partial\nuid: 1\n')).toBeUndefined();
+  });
+
+  test('getent passwd', () => {
+    expect(parseUser('linux', 'someone:x:1000:1000:Some One:/home/someone:/bin/bash\n')).toEqual({
+      gid: 1000,
+      home: '/home/someone',
+      uid: 1000,
+    });
+    expect(parseUser('linux', '')).toBeUndefined();
+  });
+});
+
+describe('parseGroup', () => {
+  test('dscacheutil and getent', () => {
+    expect(parseGroup('darwin', 'name: wheel\npassword: *\ngid: 0\nusers: root\n')).toBe(0);
+    expect(parseGroup('darwin', '')).toBeUndefined();
+    expect(parseGroup('linux', 'staff:x:50:someone\n')).toBe(50);
+    expect(parseGroup('linux', '')).toBeUndefined();
+  });
+});

package/src/launchd/host-lookup.ts

@@ -0,0 +1,94 @@
+/**
+ * User and group lookups, as argv plus a parser — split out so the parsing is tested against the
+ * real output shapes without running anything.
+ *
+ * ★ macOS FIRST, getent ELSEWHERE. macOS has no `getent`; its directory service answers through
+ *   `dscacheutil`. Shape MEASURED 2026-09-21 on macOS 27.2 (read-only query):
+ *
+ *     name: someone
+ *     password: ********
+ *     uid: 501
+ *     gid: 20
+ *     dir: /Users/someone
+ *     shell: /bin/zsh
+ *
+ *   An unknown uid printed NOTHING and exited 0 — so "no record" is an empty parse, never an
+ *   exit code. `getent` exits 2 for an unknown key; that also parses as no record.
+ * ⛔ NEVER PARSE OR KEEP THE `password:` LINE. It is a placeholder on macOS, but a parser that
+ *   copies every field would carry a hash from any host where it is not.
+ */
+import type { HostUser } from './runner.ts';
+
+const NUMERIC = /^\d+$/;
+
+/** argv for looking up a user, by name or numeric id. */
+export const userQuery = (platform: string, nameOrId: string): readonly string[] =>
+  platform === 'darwin'
+    ? [
+        '/usr/bin/dscacheutil',
+        '-q',
+        'user',
+        '-a',
+        NUMERIC.test(nameOrId) ? 'uid' : 'name',
+        nameOrId,
+      ]
+    : ['getent', 'passwd', nameOrId];
+
+/** argv for looking up a group, by name or numeric id. */
+export const groupQuery = (platform: string, nameOrId: string): readonly string[] =>
+  platform === 'darwin'
+    ? [
+        '/usr/bin/dscacheutil',
+        '-q',
+        'group',
+        '-a',
+        NUMERIC.test(nameOrId) ? 'gid' : 'name',
+        nameOrId,
+      ]
+    : ['getent', 'group', nameOrId];
+
+/** The first `key: value` record in dscacheutil output, minus any password field. */
+const firstRecord = (stdout: string): Map<string, string> => {
+  const fields = new Map<string, string>();
+  for (const line of stdout.split('\n')) {
+    if (line.trim() === '') {
+      if (fields.size > 0) break; // ⚠️ records are blank-line separated; keep the first only
+      continue;
+    }
+    const at = line.indexOf(': ');
+    if (at <= 0) continue;
+    const key = line.slice(0, at);
+    if (key === 'password') continue;
+    fields.set(key, line.slice(at + 2).trim());
+  }
+  return fields;
+};
+
+const toId = (text: string | undefined): number | undefined =>
+  text !== undefined && NUMERIC.test(text) ? Number(text) : undefined;
+
+export const parseUser = (platform: string, stdout: string): HostUser | undefined => {
+  if (platform === 'darwin') {
+    const record = firstRecord(stdout);
+    const uid = toId(record.get('uid'));
+    const gid = toId(record.get('gid'));
+    const home = record.get('dir');
+    return uid === undefined || gid === undefined || home === undefined
+      ? undefined
+      : { gid, home, uid };
+  }
+  // getent passwd: name:x:uid:gid:gecos:home:shell
+  const fields = (stdout.split('\n')[0] ?? '').split(':');
+  const uid = toId(fields[2]);
+  const gid = toId(fields[3]);
+  const home = fields[5];
+  return uid === undefined || gid === undefined || home === undefined || home === ''
+    ? undefined
+    : { gid, home, uid };
+};
+
+export const parseGroup = (platform: string, stdout: string): number | undefined => {
+  if (platform === 'darwin') return toId(firstRecord(stdout).get('gid'));
+  // getent group: name:x:gid:members
+  return toId((stdout.split('\n')[0] ?? '').split(':')[2]);
+};

package/src/launchd/index.ts

@@ -0,0 +1,26 @@
+/**
+ * launchd providers for Alchemy — declare a Mac host's jobs and their config files.
+ *
+ * ⛔ THIS BARREL IS THE PUBLIC API, AND IT IS DELIBERATELY SMALLER THAN THE DIRECTORY. The
+ *   lifecycle files, the launchctl parsers and the fake runner are internals; an `export *` would
+ *   publish them as API and make the next refactor a breaking change.
+ * ⛔ macOS HOSTS ONLY for LaunchdJob. HostFile and the runner work on any POSIX host, but the
+ *   subpath exists for the Mac: see docs/launchd.md for the cutover from nix-darwin.
+ */
+export type { HostFileAttributes, HostFileProps } from './host-file.ts';
+export { HostFile, HostFileProvider } from './host-file.ts';
+export type {
+  CalendarInterval,
+  KeepAlive,
+  LaunchdDomain,
+  LaunchdJobAttributes,
+  LaunchdJobProps,
+} from './job.ts';
+export { LaunchdJob, LaunchdJobProvider } from './job.ts';
+export type { LocalRunnerOptions } from './local-runner.ts';
+export { localRunner } from './local-runner.ts';
+export type { PlistDict, PlistValue } from './plist.ts';
+export { PlistError, renderPlist } from './plist.ts';
+export { launchdProviders } from './providers.ts';
+export type { ExecResult, FileStat, HostRunner, HostUser, WriteOptions } from './runner.ts';
+export { HostRunnerService, canActAsRoot, hostRunnerLayer } from './runner.ts';

package/src/launchd/job-form.test.ts

@@ -0,0 +1,171 @@
+/**
+ * LaunchdJob's pure half: domain parsing, the derived plist path, the props → plist mapping, and
+ * every refusal in job-validate.ts.
+ */
+import { describe, expect, test } from 'bun:test';
+import {
+  type LaunchdJobProps,
+  jobPlistDict,
+  parseDomain,
+  plistPathFor,
+  renderJob,
+  serviceTarget,
+} from './job-form.ts';
+import { RESERVED_LABEL_PREFIXES, jobProblems } from './job-validate.ts';
+
+const base: LaunchdJobProps = {
+  domain: 'system',
+  label: 'com.example.job',
+  programArguments: ['/usr/local/bin/job', '--flag'],
+};
+
+describe('domains and paths', () => {
+  test('system and gui/<uid> parse; anything else does not', () => {
+    expect(parseDomain('system')).toEqual({ kind: 'system' });
+    expect(parseDomain('gui/501')).toEqual({ kind: 'gui', uid: 501 });
+    for (const bad of ['gui/', 'gui/abc', 'user/501', 'System', 'gui/501/x']) {
+      expect(parseDomain(bad)).toBeUndefined();
+    }
+  });
+
+  test('the plist path is derived from label and domain', () => {
+    expect(plistPathFor('com.example.job', { kind: 'system' }, undefined)).toBe(
+      '/Library/LaunchDaemons/com.example.job.plist',
+    );
+    expect(plistPathFor('com.example.job', { kind: 'gui', uid: 501 }, '/Users/someone')).toBe(
+      '/Users/someone/Library/LaunchAgents/com.example.job.plist',
+    );
+  });
+
+  test('a gui domain with no home refuses rather than guessing `~`', () => {
+    expect(() => plistPathFor('x', { kind: 'gui', uid: 9 }, undefined)).toThrow('no home');
+    expect(() => plistPathFor('x', { kind: 'gui', uid: 9 }, 'relative')).toThrow('no home');
+  });
+
+  test('service target', () => {
+    expect(serviceTarget('com.example.job', 'gui/501')).toBe('gui/501/com.example.job');
+  });
+});
+
+describe('jobPlistDict', () => {
+  test('the minimum is Label and ProgramArguments — no invented defaults', () => {
+    expect(jobPlistDict(base)).toEqual({
+      Label: 'com.example.job',
+      ProgramArguments: ['/usr/local/bin/job', '--flag'],
+    });
+  });
+
+  test('every typed prop maps to its launchd.plist(5) key', () => {
+    expect(
+      jobPlistDict({
+        ...base,
+        environment: { SSL_CERT_FILE: '/etc/ssl/cert.pem' },
+        groupName: 'staff',
+        keepAlive: { crashed: true, successfulExit: false },
+        runAtLoad: true,
+        standardErrorPath: '/var/log/job.err',
+        standardOutPath: '/var/log/job.out',
+        startCalendarInterval: [{ hour: 3, minute: 30 }, { weekday: 0 }],
+        startInterval: 300,
+        throttleInterval: 30,
+        userName: 'nobody',
+        workingDirectory: '/var/empty',
+        extraKeys: { ProcessType: 'Background' },
+      }),
+    ).toEqual({
+      EnvironmentVariables: { SSL_CERT_FILE: '/etc/ssl/cert.pem' },
+      GroupName: 'staff',
+      KeepAlive: { Crashed: true, SuccessfulExit: false },
+      Label: 'com.example.job',
+      ProcessType: 'Background',
+      ProgramArguments: ['/usr/local/bin/job', '--flag'],
+      RunAtLoad: true,
+      StandardErrorPath: '/var/log/job.err',
+      StandardOutPath: '/var/log/job.out',
+      StartCalendarInterval: [{ Hour: 3, Minute: 30 }, { Weekday: 0 }],
+      StartInterval: 300,
+      ThrottleInterval: 30,
+      UserName: 'nobody',
+      WorkingDirectory: '/var/empty',
+    });
+  });
+
+  test('a single calendar entry stays a dict; keepAlive true stays a boolean; empty env is omitted', () => {
+    const dict = jobPlistDict({
+      ...base,
+      environment: {},
+      keepAlive: true,
+      startCalendarInterval: { minute: 0 },
+    });
+    expect(dict['StartCalendarInterval']).toEqual({ Minute: 0 });
+    expect(dict['KeepAlive']).toBe(true);
+    expect('EnvironmentVariables' in dict).toBe(false);
+  });
+
+  test('the digest is stable across key order and changes with any value', () => {
+    const one = renderJob({ ...base, environment: { A: '1', B: '2' } });
+    const two = renderJob({ ...base, environment: { B: '2', A: '1' } });
+    expect(one.sha256).toBe(two.sha256);
+    expect(one.sha256).toMatch(/^[0-9a-f]{64}$/);
+    expect(renderJob({ ...base, runAtLoad: true }).sha256).not.toBe(one.sha256);
+    expect(new TextDecoder().decode(one.bytes)).toBe(one.text);
+  });
+});
+
+describe('jobProblems', () => {
+  test('a well-formed job has none', () => {
+    expect(jobProblems(base)).toEqual([]);
+    expect(
+      jobProblems({ ...base, domain: 'gui/501', startCalendarInterval: { weekday: 7 } }),
+    ).toEqual([]);
+  });
+
+  test.each([
+    [
+      'a slash in the label (it becomes a file name)',
+      { label: 'com.example/../evil' },
+      'label must be',
+    ],
+    ['a leading dot', { label: '.hidden' }, 'label must be'],
+    ['an unknown domain', { domain: 'user/501' as never }, 'domain must be'],
+    ['no program', { programArguments: [] }, 'must name a program'],
+    ['a relative program', { programArguments: ['job'] }, 'absolute path'],
+    ['a bad env name', { environment: { 'A-B': 'x' } }, 'not a valid variable name'],
+    ['a zero startInterval', { startInterval: 0 }, 'startInterval'],
+    ['a fractional throttleInterval', { throttleInterval: 1.5 }, 'throttleInterval'],
+    ['an hour of 24', { startCalendarInterval: { hour: 24 } }, 'hour must be 0–23'],
+    ['a day of 0', { startCalendarInterval: [{ day: 0 }] }, 'day must be 1–31'],
+    ['an empty calendar list', { startCalendarInterval: [] }, 'empty list'],
+    ['keepAlive with no condition', { keepAlive: {} }, 'names no condition'],
+    [
+      'a relative log path',
+      { standardOutPath: 'log.txt' },
+      'standardOutPath must be an absolute path',
+    ],
+    [
+      'userName on an agent',
+      { domain: 'gui/501' as const, userName: 'nobody' },
+      'only to the system domain',
+    ],
+    ['extraKeys naming a typed key', { extraKeys: { KeepAlive: true } }, 'extraKeys.KeepAlive'],
+    ['extraKeys naming Program', { extraKeys: { Program: '/bin/x' } }, 'extraKeys.Program'],
+    ['a secret-looking env var', { environment: { API_TOKEN: 'x' } }, 'unencrypted'],
+  ])('refuses %s', (_name, patch, message) => {
+    expect(jobProblems({ ...base, ...patch } as LaunchdJobProps).join('\n')).toContain(message);
+  });
+
+  test.each(RESERVED_LABEL_PREFIXES.map((prefix) => [prefix]))(
+    'refuses labels under %s',
+    (prefix) => {
+      expect(jobProblems({ ...base, label: `${prefix}job` }).join('\n')).toContain(
+        'another tool owns',
+      );
+    },
+  );
+
+  test('reports every problem at once, so one plan shows the whole list', () => {
+    expect(
+      jobProblems({ ...base, label: '/x', programArguments: ['rel'], startInterval: -1 }).length,
+    ).toBe(3);
+  });
+});

package/src/launchd/job-form.ts

@@ -0,0 +1,180 @@
+/**
+ * LaunchdJob's props, attributes and the pure half of the provider: domain parsing, the plist path,
+ * and the props → plist mapping whose SHA-256 is the whole diff.
+ *
+ * ★ KEY NAMES AND MEANINGS FROM launchd.plist(5), checked against the 148 nix-darwin daemons on a
+ *   macOS 27.2 host on 2026-09-21 (read-only, from /nix/store): Label, ProgramArguments, RunAtLoad,
+ *   KeepAlive (boolean or {SuccessfulExit}), ThrottleInterval, StandardOutPath/StandardErrorPath,
+ *   EnvironmentVariables, UserName, StartInterval and StartCalendarInterval are the keys in real
+ *   use. Everything rarer goes through `extraKeys`.
+ */
+import { createHash } from 'node:crypto';
+import { type PlistDict, type PlistValue, renderPlist } from './plist.ts';
+
+/** `system` (LaunchDaemons, root) or one user's login session, `gui/<uid>` (LaunchAgents). */
+export type LaunchdDomain = 'system' | `gui/${number}`;
+
+/** One StartCalendarInterval entry. An omitted field is a wildcard, as in cron. */
+export type CalendarInterval = {
+  readonly minute?: number;
+  readonly hour?: number;
+  readonly day?: number;
+  /** 0 and 7 are both Sunday. */
+  readonly weekday?: number;
+  readonly month?: number;
+};
+
+/** `true` = always restart; the object form restarts only on the named conditions. */
+export type KeepAlive = boolean | { readonly successfulExit?: boolean; readonly crashed?: boolean };
+
+export interface LaunchdJobProps {
+  /** Reverse-DNS label. Unique per domain; also the plist's file name. */
+  label: string;
+  domain: LaunchdDomain;
+  /** argv; the first element must be an absolute path. */
+  programArguments: readonly string[];
+  /**
+   * ⛔ NON-SECRET VALUES ONLY. Props are stored unencrypted in Alchemy state, and these also land in
+   *   the plist on disk and in `launchctl print`. Pass a secret as a FILE PATH that a secret renderer
+   *   (openbao-agent) maintains — secret-tripwire.ts refuses the obvious mistakes.
+   */
+  environment?: Readonly<Record<string, string>>;
+  runAtLoad?: boolean;
+  keepAlive?: KeepAlive;
+  /** Seconds between starts. */
+  startInterval?: number;
+  startCalendarInterval?: CalendarInterval | readonly CalendarInterval[];
+  /** Minimum seconds between (re)starts; launchd's default is 10. */
+  throttleInterval?: number;
+  standardOutPath?: string;
+  standardErrorPath?: string;
+  workingDirectory?: string;
+  /** Run as this user. ⚠️ System domain only — launchd ignores it for agents, so it is refused. */
+  userName?: string;
+  /** Run as this group. ⚠️ System domain only, like `userName`. */
+  groupName?: string;
+  /**
+   * Any other launchd.plist(5) key, verbatim (`ProcessType`, `SoftResourceLimits`, …).
+   * ⛔ A key the typed props own is refused, so one job can never say two things.
+   */
+  extraKeys?: PlistDict;
+}
+
+export interface LaunchdJobAttributes {
+  label: string;
+  domain: LaunchdDomain;
+  /** `<domain>/<label>` — what `launchctl print` / `bootout` take. */
+  serviceTarget: string;
+  plistPath: string;
+  /** SHA-256 of the plist bytes last bootstrapped (reconcile) or found on disk (read). */
+  plistSha256: string;
+  /** Bootstrapped into the domain — not necessarily running. */
+  loaded: boolean;
+  /** launchd's own word: `running`, `not running`, … */
+  state?: string;
+  pid?: number;
+  lastExitCode?: number;
+}
+
+export type ParsedDomain =
+  | { readonly kind: 'system' }
+  | { readonly kind: 'gui'; readonly uid: number };
+
+export const parseDomain = (domain: string): ParsedDomain | undefined => {
+  if (domain === 'system') return { kind: 'system' };
+  const match = /^gui\/(\d+)$/.exec(domain);
+  return match?.[1] === undefined ? undefined : { kind: 'gui', uid: Number(match[1]) };
+};
+
+export const serviceTarget = (label: string, domain: LaunchdDomain): string => `${domain}/${label}`;
+
+/**
+ * Where launchd expects the job's plist. ★ Derived, never declared: a daemon's plist outside
+ *   /Library/LaunchDaemons is not bootstrapped at boot, so a free-form path would be a job that
+ *   silently stops existing after the next restart.
+ */
+export const plistPathFor = (
+  label: string,
+  domain: ParsedDomain,
+  home: string | undefined,
+): string => {
+  if (domain.kind === 'system') return `/Library/LaunchDaemons/${label}.plist`;
+  // ⛔ No `~` fallback: the provider may run as root, whose `~` is not the agent owner's home.
+  if (home === undefined || !home.startsWith('/')) {
+    throw new Error(`gui/${String(domain.uid)}: no home directory for that uid on this host`);
+  }
+  return `${home}/Library/LaunchAgents/${label}.plist`;
+};
+
+/** Plist keys the typed props own — `extraKeys` may not name them. `Program` is refused too. */
+export const OWNED_KEYS: readonly string[] = [
+  'EnvironmentVariables',
+  'GroupName',
+  'KeepAlive',
+  'Label',
+  'Program',
+  'ProgramArguments',
+  'RunAtLoad',
+  'StandardErrorPath',
+  'StandardOutPath',
+  'StartCalendarInterval',
+  'StartInterval',
+  'ThrottleInterval',
+  'UserName',
+  'WorkingDirectory',
+];
+
+const calendarDict = (entry: CalendarInterval): PlistDict => {
+  const dict: Record<string, PlistValue> = {};
+  if (entry.minute !== undefined) dict['Minute'] = entry.minute;
+  if (entry.hour !== undefined) dict['Hour'] = entry.hour;
+  if (entry.day !== undefined) dict['Day'] = entry.day;
+  if (entry.weekday !== undefined) dict['Weekday'] = entry.weekday;
+  if (entry.month !== undefined) dict['Month'] = entry.month;
+  return dict;
+};
+
+const keepAliveValue = (keepAlive: KeepAlive): PlistValue => {
+  if (typeof keepAlive === 'boolean') return keepAlive;
+  const dict: Record<string, PlistValue> = {};
+  if (keepAlive.successfulExit !== undefined) dict['SuccessfulExit'] = keepAlive.successfulExit;
+  if (keepAlive.crashed !== undefined) dict['Crashed'] = keepAlive.crashed;
+  return dict;
+};
+
+/** The plist dict for a job. ⚠️ Assumes jobProblems() came back empty. */
+export const jobPlistDict = (props: LaunchdJobProps): PlistDict => {
+  const dict: Record<string, PlistValue> = { ...props.extraKeys };
+  dict['Label'] = props.label;
+  dict['ProgramArguments'] = [...props.programArguments];
+  const env = props.environment ?? {};
+  if (Object.keys(env).length > 0) dict['EnvironmentVariables'] = { ...env };
+  if (props.runAtLoad !== undefined) dict['RunAtLoad'] = props.runAtLoad;
+  if (props.keepAlive !== undefined) dict['KeepAlive'] = keepAliveValue(props.keepAlive);
+  if (props.startInterval !== undefined) dict['StartInterval'] = props.startInterval;
+  const calendar = props.startCalendarInterval;
+  if (calendar !== undefined) {
+    dict['StartCalendarInterval'] = Array.isArray(calendar)
+      ? (calendar as readonly CalendarInterval[]).map(calendarDict)
+      : calendarDict(calendar as CalendarInterval);
+  }
+  if (props.throttleInterval !== undefined) dict['ThrottleInterval'] = props.throttleInterval;
+  if (props.standardOutPath !== undefined) dict['StandardOutPath'] = props.standardOutPath;
+  if (props.standardErrorPath !== undefined) dict['StandardErrorPath'] = props.standardErrorPath;
+  if (props.workingDirectory !== undefined) dict['WorkingDirectory'] = props.workingDirectory;
+  if (props.userName !== undefined) dict['UserName'] = props.userName;
+  if (props.groupName !== undefined) dict['GroupName'] = props.groupName;
+  return dict;
+};
+
+export const sha256Hex = (bytes: Uint8Array | string): string =>
+  createHash('sha256').update(bytes).digest('hex');
+
+/** The rendered plist and its digest — the only thing LaunchdJob compares. */
+export const renderJob = (
+  props: LaunchdJobProps,
+): { text: string; bytes: Uint8Array; sha256: string } => {
+  const text = renderPlist(jobPlistDict(props));
+  const bytes = new TextEncoder().encode(text);
+  return { bytes, sha256: sha256Hex(bytes), text };
+};