@homeflare/alchemy 0.5.0 → 0.7.0

package/src/launchd/host-file-form.ts

@@ -0,0 +1,71 @@
+/**
+ * HostFile's props, attributes and validation — the pure half of the provider.
+ *
+ * ⛔ `content` IS NEVER A SECRET. Alchemy stores props unencrypted, so the content of every HostFile
+ *   sits in the state store and in every plan diff. A secret file stays RENDERED BY A SECRET
+ *   RENDERER (openbao-agent templates, on this estate) that fetches it at run time; the stack
+ *   declares only non-secret config, and at most the PATH the renderer writes to.
+ *   secret-tripwire.ts refuses the obvious case (a PEM private key); nothing can catch all of them.
+ */
+import { fileSecretProblems } from './secret-tripwire.ts';
+
+export interface HostFileProps {
+  /** Absolute path. The parent directory must already exist. */
+  path: string;
+  /** UTF-8 text. ⛔ Never a secret — see the file header. */
+  content: string;
+  /** Permission bits. @default 0o644 */
+  mode?: number;
+  /** User name or numeric uid. Omitted: whoever the runner writes as (a rewrite keeps no owner). */
+  owner?: string | number;
+  /** Group name or numeric gid. Omitted: the directory's default group. */
+  group?: string | number;
+}
+
+export interface HostFileAttributes {
+  path: string;
+  /** SHA-256 of the bytes on disk. */
+  sha256: string;
+  mode: number;
+  uid: number;
+  gid: number;
+  size: number;
+}
+
+export const DEFAULT_MODE = 0o644;
+
+const identityProblems = (name: string, value: string | number | undefined): string[] => {
+  if (value === undefined) return [];
+  if (typeof value === 'number') {
+    return Number.isSafeInteger(value) && value >= 0
+      ? []
+      : [`${name} must be a non-negative integer id`];
+  }
+  return /^[A-Za-z_][A-Za-z0-9_.-]*$/.test(value) || /^\d+$/.test(value)
+    ? []
+    : [`${name} ${JSON.stringify(value)} is not a valid user or group name`];
+};
+
+export const fileProblems = (props: HostFileProps): string[] => {
+  const found: string[] = [];
+  const { path } = props;
+  if (!path.startsWith('/')) found.push('path must be absolute');
+  // ★ One spelling per file: `a/./b`, `a//b` and `a/../b` would each be a second resource for the
+  //   same inode, and `..` is how a derived path walks out of the directory it was meant for.
+  if (
+    path.endsWith('/') ||
+    path
+      .split('/')
+      .slice(1)
+      .some((part) => part === '' || part === '.' || part === '..')
+  ) {
+    found.push('path must be normalised (no trailing slash, no empty, "." or ".." segments)');
+  }
+  if (path.includes('\x00')) found.push('path contains NUL');
+  const mode = props.mode ?? DEFAULT_MODE;
+  if (!Number.isSafeInteger(mode) || mode < 0 || mode > 0o7777) found.push('mode must be 0–0o7777');
+  found.push(...identityProblems('owner', props.owner));
+  found.push(...identityProblems('group', props.group));
+  found.push(...fileSecretProblems(props.content));
+  return found;
+};

package/src/launchd/host-file-lifecycle.test.ts

@@ -0,0 +1,198 @@
+/**
+ * HostFile's lifecycle against the fake host (no real writes), plus its validation.
+ */
+import { describe, expect, test } from 'bun:test';
+import { fakeRunner } from './fake-runner.ts';
+import { type HostFileProps, fileProblems } from './host-file-form.ts';
+import { deleteFile, diffFile, readFileAttributes, reconcileFile } from './host-file-lifecycle.ts';
+
+const PATH = '/etc/example/app.conf';
+const file: HostFileProps = { content: 'listen = 127.0.0.1:9000\n', path: PATH };
+
+const host = (euid = 0) =>
+  fakeRunner({
+    dirs: { '/etc/example': 0, '/Users/someone/cfg': 501 },
+    euid,
+    groups: { staff: 20, wheel: 0 },
+    users: {
+      root: { gid: 0, home: '/var/root', uid: 0 },
+      someone: { gid: 20, home: '/Users/someone', uid: 501 },
+    },
+  });
+
+const writeCount = (calls: string[][]) => calls.filter((call) => call[0] === 'write').length;
+
+describe('create and read back', () => {
+  test('writes the content with the default mode 0644 and returns what is on disk', async () => {
+    const fake = host();
+    const attrs = await reconcileFile(fake.runner, file);
+    expect(attrs).toMatchObject({ mode: 0o644, path: PATH, size: file.content.length, uid: 0 });
+    expect(new TextDecoder().decode(fake.files.get(PATH)?.bytes)).toBe(file.content);
+    expect(await readFileAttributes(fake.runner, PATH)).toEqual(attrs);
+  });
+
+  test('owner and group resolve by name or by id', async () => {
+    const fake = host();
+    const attrs = await reconcileFile(fake.runner, {
+      ...file,
+      group: 'staff',
+      mode: 0o640,
+      owner: 'someone',
+    });
+    expect(attrs).toMatchObject({ gid: 20, mode: 0o640, uid: 501 });
+    const byId = await reconcileFile(fake.runner, { ...file, group: 0, owner: '0' }, attrs);
+    expect(byId).toMatchObject({ gid: 0, uid: 0 });
+  });
+
+  test('an already-matching file is not rewritten', async () => {
+    const fake = host();
+    await reconcileFile(fake.runner, file);
+    await reconcileFile(fake.runner, file);
+    expect(writeCount(fake.calls)).toBe(1);
+  });
+});
+
+describe('diff', () => {
+  test('noop, then update on content, mode or owner drift', async () => {
+    const fake = host();
+    const output = await reconcileFile(fake.runner, { ...file, owner: 'root' });
+    expect(await diffFile(fake.runner, { ...file, owner: 'root' }, output)).toEqual({
+      action: 'noop',
+    });
+    expect(await diffFile(fake.runner, { ...file, content: 'x\n' }, output)).toEqual({
+      action: 'update',
+    });
+    expect(await diffFile(fake.runner, { ...file, mode: 0o600 }, output)).toEqual({
+      action: 'update',
+    });
+    expect(await diffFile(fake.runner, { ...file, owner: 'someone' }, output)).toEqual({
+      action: 'update',
+    });
+    const entry = fake.files.get(PATH);
+    if (entry === undefined) throw new Error('no file');
+    fake.files.set(PATH, { ...entry, mode: 0o666 });
+    expect(await diffFile(fake.runner, { ...file, owner: 'root' }, output)).toEqual({
+      action: 'update',
+    });
+  });
+
+  test('a file deleted behind our back is an update', async () => {
+    const fake = host();
+    const output = await reconcileFile(fake.runner, file);
+    fake.files.delete(PATH);
+    expect(await diffFile(fake.runner, file, output)).toEqual({ action: 'update' });
+  });
+
+  test('a new path is a create-before-delete replace', async () => {
+    const fake = host();
+    const output = await reconcileFile(fake.runner, file);
+    expect(
+      await diffFile(fake.runner, { ...file, path: '/etc/example/other.conf' }, output),
+    ).toEqual({ action: 'replace' });
+  });
+});
+
+describe('refusals', () => {
+  test('chown to another user as a non-root deployer', async () => {
+    const fake = host(501);
+    await expect(
+      reconcileFile(fake.runner, { ...file, owner: 'root', path: '/Users/someone/cfg/a' }),
+    ).rejects.toThrow('only root may chown');
+  });
+
+  test('a symlink or a directory at the path is never replaced', async () => {
+    const fake = host();
+    fake.files.set(PATH, { bytes: new Uint8Array(), gid: 0, kind: 'symlink', mode: 0o755, uid: 0 });
+    await expect(reconcileFile(fake.runner, file)).rejects.toThrow('is a symlink');
+    await expect(reconcileFile(fake.runner, { ...file, path: '/etc/example' })).rejects.toThrow(
+      'is a directory',
+    );
+  });
+
+  test('an unknown owner or group', async () => {
+    const fake = host();
+    await expect(reconcileFile(fake.runner, { ...file, owner: 'nobody-here' })).rejects.toThrow(
+      'no user',
+    );
+    await expect(reconcileFile(fake.runner, { ...file, group: 'nogroup' })).rejects.toThrow(
+      'no group',
+    );
+  });
+
+  test('a missing parent directory surfaces as the error it is', async () => {
+    await expect(reconcileFile(host().runner, { ...file, path: '/nowhere/x' })).rejects.toThrow(
+      'ENOENT',
+    );
+  });
+
+  test.each([
+    ['a relative path', { path: 'etc/x' }, 'absolute'],
+    ['a dot-dot segment', { path: '/etc/../x' }, 'normalised'],
+    ['a trailing slash', { path: '/etc/x/' }, 'normalised'],
+    ['a double slash', { path: '/etc//x' }, 'normalised'],
+    ['a mode above 0o7777', { mode: 0o10000 }, 'mode'],
+    ['a bad owner name', { owner: 'a b' }, 'not a valid user'],
+    ['a negative gid', { group: -1 }, 'non-negative'],
+    // ⚠️ Split so gitleaks' private-key rule does not flag the fixture (secret-tripwire.test.ts).
+    ['a private key', { content: `-----BEGIN EC ${'PRIVATE'} KEY-----\n` }, 'openbao-agent'],
+  ])('%s', (_name, patch, message) => {
+    expect(fileProblems({ ...file, ...patch } as HostFileProps).join('\n')).toContain(message);
+  });
+});
+
+describe('files this resource does not own, and moves', () => {
+  const OTHER = '/etc/example/other.conf';
+
+  test('a different file at a path with no prior state is refused and left alone', async () => {
+    // ★ The new path of a replace: the engine's adoption probe never looked there.
+    const fake = host();
+    fake.files.set(OTHER, {
+      bytes: new Uint8Array([7]),
+      gid: 0,
+      kind: 'file',
+      mode: 0o600,
+      uid: 0,
+    });
+    await expect(reconcileFile(fake.runner, { ...file, path: OTHER })).rejects.toThrow(
+      'not this resource',
+    );
+    expect(fake.files.get(OTHER)?.bytes).toEqual(new Uint8Array([7]));
+  });
+
+  test('a move that reaches reconcile as an update writes the new path, then removes the old', async () => {
+    const fake = host();
+    const output = await reconcileFile(fake.runner, file);
+    const moved = await reconcileFile(fake.runner, { ...file, path: OTHER }, output);
+    expect(moved.path).toBe(OTHER);
+    expect(fake.files.has(OTHER)).toBe(true);
+    expect(fake.files.has(PATH)).toBe(false);
+  });
+
+  test('a create whose read-back fails is rolled back, so the next plan finds nothing', async () => {
+    const fake = host();
+    const runner = {
+      ...fake.runner,
+      writeFileAtomic: (path: string, _bytes: Uint8Array, options: { mode: number }) =>
+        fake.runner.writeFileAtomic(path, new Uint8Array([0]), options),
+    };
+    await expect(reconcileFile(runner, file)).rejects.toThrow('does not match');
+    expect(fake.files.has(PATH)).toBe(false);
+  });
+});
+
+describe('delete', () => {
+  test('removes the file and is idempotent', async () => {
+    const fake = host();
+    const output = await reconcileFile(fake.runner, file);
+    await deleteFile(fake.runner, output);
+    expect(fake.files.has(PATH)).toBe(false);
+    await deleteFile(fake.runner, output);
+  });
+
+  test('refuses once the path has become something other than a file', async () => {
+    const fake = host();
+    const output = await reconcileFile(fake.runner, file);
+    fake.files.set(PATH, { bytes: new Uint8Array(), gid: 0, kind: 'symlink', mode: 0o755, uid: 0 });
+    await expect(deleteFile(fake.runner, output)).rejects.toThrow('not removing');
+  });
+});

package/src/launchd/host-file-lifecycle.ts

@@ -0,0 +1,164 @@
+/**
+ * HostFile's read / diff / reconcile / delete as plain async functions over a HostRunner, so the
+ * lifecycle runs against fake-runner.ts in tests.
+ *
+ * ⛔ SYMLINKS AND DIRECTORIES ARE REFUSED, NOT REPLACED. rename(2) over a symlink replaces the LINK,
+ *   so a path that is a symlink (nix-darwin's /etc entries point into /nix/store) would be quietly
+ *   taken from the tool that owns it — which puts it back, or refuses its next activation. Remove
+ *   the path from its owner first, then declare it here.
+ */
+import type { Diff } from 'alchemy/Diff';
+import {
+  DEFAULT_MODE,
+  type HostFileAttributes,
+  type HostFileProps,
+  fileProblems,
+} from './host-file-form.ts';
+import { sha256Hex } from './job-form.ts';
+import { type HostRunner, canActAsRoot } from './runner.ts';
+
+type Desired = {
+  readonly bytes: Uint8Array;
+  readonly sha256: string;
+  readonly mode: number;
+  readonly uid?: number;
+  readonly gid?: number;
+};
+
+const refuse = (path: string, message: string): Error => new Error(`Host.File ${path}: ${message}`);
+
+const numericId = (value: string | number): number | undefined =>
+  typeof value === 'number' ? value : /^\d+$/.test(value) ? Number(value) : undefined;
+
+/** Validate, then resolve owner/group names to ids through the runner. */
+export const desiredFile = async (runner: HostRunner, props: HostFileProps): Promise<Desired> => {
+  const found = fileProblems(props);
+  if (found.length > 0) throw refuse(props.path, found.join('; '));
+  const bytes = new TextEncoder().encode(props.content);
+  let uid: number | undefined;
+  let gid: number | undefined;
+  if (props.owner !== undefined) {
+    uid = numericId(props.owner) ?? (await runner.lookupUser(String(props.owner)))?.uid;
+    if (uid === undefined) throw refuse(props.path, `no user ${String(props.owner)} on this host`);
+  }
+  if (props.group !== undefined) {
+    gid = numericId(props.group) ?? (await runner.lookupGroup(String(props.group)));
+    if (gid === undefined) throw refuse(props.path, `no group ${String(props.group)} on this host`);
+  }
+  return {
+    bytes,
+    mode: props.mode ?? DEFAULT_MODE,
+    sha256: sha256Hex(bytes),
+    ...(uid === undefined ? {} : { uid }),
+    ...(gid === undefined ? {} : { gid }),
+  };
+};
+
+/** The file as it is now, or `undefined` when nothing is at the path. Non-files read with no digest. */
+export const readFileAttributes = async (
+  runner: HostRunner,
+  path: string,
+): Promise<HostFileAttributes | undefined> => {
+  const stat = await runner.stat(path);
+  if (stat === undefined) return undefined;
+  const bytes = stat.kind === 'file' ? await runner.readFile(path) : undefined;
+  return {
+    gid: stat.gid,
+    mode: stat.mode,
+    path,
+    sha256: bytes === undefined ? '' : sha256Hex(bytes),
+    size: stat.size,
+    uid: stat.uid,
+  };
+};
+
+const matches = (live: HostFileAttributes, want: Desired): boolean =>
+  live.sha256 === want.sha256 &&
+  live.mode === want.mode &&
+  (want.uid === undefined || live.uid === want.uid) &&
+  (want.gid === undefined || live.gid === want.gid);
+
+export const diffFile = async (
+  runner: HostRunner,
+  news: HostFileProps,
+  output: HostFileAttributes,
+): Promise<Diff> => {
+  // ★ Create-before-delete: two paths can hold two files at once, so nothing forces deleteFirst.
+  if (news.path !== output.path) return { action: 'replace' };
+  const want = await desiredFile(runner, news);
+  if (want.sha256 !== output.sha256) return { action: 'update' };
+  const live = await readFileAttributes(runner, news.path);
+  return live !== undefined && matches(live, want) ? { action: 'noop' } : { action: 'update' };
+};
+
+export const reconcileFile = async (
+  runner: HostRunner,
+  props: HostFileProps,
+  output?: HostFileAttributes,
+): Promise<HostFileAttributes> => {
+  const want = await desiredFile(runner, props);
+  // ⛔ NO SILENT SUDO: handing a file to another user is root's call (chown(2)), so say so up front.
+  if (want.uid !== undefined && want.uid !== runner.effectiveUid() && !canActAsRoot(runner)) {
+    throw refuse(
+      props.path,
+      `owner ${String(props.owner)} is not the deploying user; only root may chown. Deploy as root ` +
+        'or through a privileged HostRunner (privileged: true). This provider never calls sudo.',
+    );
+  }
+  const stat = await runner.stat(props.path);
+  if (stat !== undefined && stat.kind !== 'file') {
+    throw refuse(
+      props.path,
+      `is a ${stat.kind}; remove it from whatever owns it before declaring it here`,
+    );
+  }
+  const before = stat === undefined ? undefined : await readFileAttributes(runner, props.path);
+  // ⚠️ An `output` at another path: the engine planned an UPDATE across a move, which it does
+  //   when diff could not see the new path (host-file.ts). Finish it the way a replace would.
+  const moved = output !== undefined && output.path !== props.path;
+  const prior = moved ? undefined : output;
+  /**
+   * ⛔ A FILE THIS RESOURCE DOES NOT OWN IS NEVER OVERWRITTEN. With no prior state for this path,
+   *   the engine's adoption probe has already refused anything it found — except at the new path of
+   *   a replace, where it reads nothing. A path typo there would otherwise overwrite, say, a system
+   *   file that a fresh declaration of the same path would have been refused as `Unowned`.
+   */
+  if (prior === undefined && before !== undefined && !matches(before, want)) {
+    throw refuse(
+      props.path,
+      'already exists and is not this resource. Remove it, or declare it as a new resource and ' +
+        'deploy with --adopt.',
+    );
+  }
+  if (before === undefined || !matches(before, want)) {
+    await runner.writeFileAtomic(props.path, want.bytes, {
+      mode: want.mode,
+      ...(want.uid === undefined ? {} : { uid: want.uid }),
+      ...(want.gid === undefined ? {} : { gid: want.gid }),
+    });
+  }
+  // ⚠️ READ BACK, never echo the declaration: a umask, an ACL or a runner that ignored `uid` shows
+  //   up here as a refusal instead of as a forever-`update`.
+  const after = await readFileAttributes(runner, props.path);
+  if (after === undefined || !matches(after, want)) {
+    // ⚠️ Roll back a CREATE: left behind, the next plan's recovery `read` finds a file with no
+    //   state, reports it `Unowned`, and every later deploy demands --adopt for our own file.
+    if (before === undefined) await runner.removeFile(props.path).catch(() => undefined);
+    throw refuse(
+      props.path,
+      'the write returned but the file on disk does not match the declaration',
+    );
+  }
+  // ★ Create-before-delete, as the replace would have been: the old path goes only once the new
+  //   one is written and verified.
+  if (moved) await deleteFile(runner, output);
+  return after;
+};
+
+/** Remove the file. Idempotent. ⛔ Refuses a path that has since become a symlink or directory. */
+export const deleteFile = async (runner: HostRunner, output: HostFileAttributes): Promise<void> => {
+  const stat = await runner.stat(output.path);
+  if (stat === undefined) return;
+  if (stat.kind !== 'file') throw refuse(output.path, `is now a ${stat.kind}; not removing it`);
+  await runner.removeFile(output.path);
+};

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