@homeflare/alchemy 0.7.0 → 0.10.0

package/src/caddy/config.ts

@@ -5,8 +5,7 @@
  * - create / update — `POST /adapt` (validate), `POST /load` with `text/caddyfile` (a graceful
  *   reload; Caddy keeps the old config if it refuses the new one, and the error names why), then
  *   `GET /config/` and insist it matches. Skipped when Caddy already runs this config.
- * - read — the digest of `GET /config/`. ★ WITH NO STATE, A RUNNING CADDY IS ADOPTED: its live
- *   config becomes the starting point, and the deploy's forced update loads the declared one.
+ * - read — the digest of `GET /config/`. With no state it is the adoption probe (below).
  * - diff — declared, live and stored digests (config-lifecycle.ts). Never `replace`.
  * - delete — ⛔ NOTHING. See below.
  *
@@ -15,17 +14,24 @@
  *   servers. `retain` is the default (the engine never calls delete); with `destroy` the handler
  *   still only forgets. It never calls `/stop` (which exits the process) or `DELETE /config/`.
  *   To empty a Caddy, do it by hand at its admin API.
+ * ⛔ NOTHING IS ADOPTED SILENTLY (decision, 2026-09-21 — the house rule HostFile and LaunchdJob
+ *   keep). With no state, a running Caddy whose live config IS the declared one reads as ours (the
+ *   adoption changes nothing); any other config reads as `Unowned`, and the plan refuses it unless
+ *   the deploy runs with `--adopt`. A Caddy serving nothing reads as absent: a create. Where the
+ *   engine skips that probe, reconcile refuses the same takeover (config-lifecycle.ts).
  * ⛔ `caddyfile` IS NEVER A SECRET — see config-form.ts; refused before anything is sent.
  * ⚠️ WHICH CADDY is the transport's (providers.ts), not a prop: one CaddyAdmin per stack.
  */
 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 '../launchd/host-effect.ts';
+import { adoptEnabled } from '../ownership/adopt.ts';
 import { CaddyAdminService, CaddyUnreachableError } from './admin.ts';
 import type { CaddyConfigAttributes, CaddyConfigProps } from './config-form.ts';
-import { diffConfig, readLive, reconcileConfig } from './config-lifecycle.ts';
+import { diffConfig, probeLive, readLive, reconcileConfig } from './config-lifecycle.ts';
 
 export type { CaddyConfigAttributes, CaddyConfigProps } from './config-form.ts';
 
@@ -64,17 +70,40 @@ export const CaddyConfigProvider = () =>
     CaddyConfig,
     Effect.gen(function* () {
       const admin = yield* CaddyAdminService;
+      /** The probe, branded for the engine: plain when ours, `Unowned` otherwise. */
+      const probe = (caddyfile: string | undefined, sourceFile: string | undefined) =>
+        Effect.flatMap(
+          lift(() => probeLive(admin, caddyfile, sourceFile)),
+          (found) => {
+            if (found === undefined) return Effect.succeed(undefined);
+            if (found.ours) return Effect.succeed(found.attributes);
+            const unowned = Unowned(found.attributes);
+            return found.unchecked === undefined
+              ? Effect.succeed(unowned)
+              : Effect.as(
+                  Effect.logWarning(
+                    `Caddy.Config at ${admin.endpoint}: the running config could not be compared ` +
+                      `with the declared Caddyfile (${found.unchecked}), so it is not treated as ours`,
+                  ),
+                  unowned,
+                );
+          },
+        );
       return CaddyConfig.Provider.of({
         /** ⛔ A Caddy has one config; there is nothing to enumerate, and nothing for nuke to delete. */
         list: () => Effect.succeed([]),
 
         /**
-         * ★ Plain attributes, never `Unowned`: a Caddy on this host's loopback admin API is the one
-         *   the stack means (the transport refuses anything else), and adopting reads — it changes
-         *   nothing until reconcile loads the declared Caddyfile.
+         * With state: the live attributes, which diff compares. With none, the ADOPTION PROBE —
+         * `olds` is the declaration (Plan.ts passes `news`), and only a live config equal to it is
+         * ours. ⚠️ A running Caddy is still the one the stack means (the transport reaches only
+         * loopback), but WHOSE CONFIG it runs is not: a person, another tool or another stack.
          */
-        read: ({ olds }) =>
-          lift(() => readLive(admin, resolvedString(olds, 'sourceFile'))).pipe(
+        read: ({ olds, output }) =>
+          (output === undefined
+            ? probe(resolvedString(olds, 'caddyfile'), resolvedString(olds, 'sourceFile'))
+            : lift(() => readLive(admin, resolvedString(olds, 'sourceFile')))
+          ).pipe(
             // ★ Nothing to adopt from a Caddy that is down: plan a create, which is the same load.
             Effect.catchIf(unreachable, planWithoutCaddy(admin, undefined)),
           ),
@@ -101,9 +130,18 @@ export const CaddyConfigProvider = () =>
           }).pipe(Effect.catchIf(unreachable, update));
         },
 
-        reconcile: ({ news }) =>
+        reconcile: ({ fqn, news, output }) =>
           Effect.gen(function* () {
-            const applied = yield* lift(() => reconcileConfig(admin, news));
+            // ⛔ State is authority over the Caddy it was applied to, and no other. With none (the
+            //   engine may not have probed: see reconcileConfig), or with the transport now at
+            //   another endpoint, only adoption — `--adopt`, or this resource's own `adopt(…)`,
+            //   as the planner resolves it — loads over a config the stack cannot claim.
+            const sameCaddy = output !== undefined && output.endpoint === admin.endpoint;
+            const takeOver = sameCaddy || (yield* adoptEnabled(fqn));
+            const stored = output === undefined ? {} : { stored: output.configSha256 };
+            const applied = yield* lift(() =>
+              reconcileConfig(admin, news, { takeOver, ...stored }),
+            );
             for (const warning of applied.warnings) {
               yield* Effect.logWarning(`Caddy.Config at ${admin.endpoint}: ${warning}`);
             }

package/src/caddy/fake-caddy.ts

@@ -17,6 +17,9 @@
  * ★ `listenPort` is the port Caddy BELIEVES it listens on — its Host check uses it — while the
  *   fake really listens on an ephemeral one: a Caddy on its default :2019 behind a forward.
  */
+import type { CaddyAdmin } from './admin.ts';
+import { localCaddyAdmin } from './local-admin.ts';
+
 export type Seen = {
   readonly method: string;
   readonly path: string;
@@ -158,3 +161,19 @@ export const fakeCaddy = (
     stop: () => void server.stop(true),
   };
 };
+
+/**
+ * A fake Caddy on its DEFAULT :2019 behind a forward (`hostHeader`), and the transport to it.
+ * ★ Addressed that way so a Caddyfile with no `admin` line — the common case — passes the guard.
+ *   A Caddy reached on any other port needs `admin <address>` declared, or the first load would
+ *   move it (admin-guard.ts).
+ */
+export const fakeDefaultCaddy = (running?: unknown): { admin: CaddyAdmin; caddy: FakeCaddy } => {
+  const caddy = fakeCaddy({ listenPort: 2019, ...(running === undefined ? {} : { running }) });
+  const admin = localCaddyAdmin({
+    address: caddy.address,
+    hostHeader: '127.0.0.1:2019',
+    retries: 0,
+  });
+  return { admin, caddy };
+};

package/src/caddy/index.ts

@@ -6,7 +6,8 @@
  *   the digest, the guards and the admin calls are internals; an `export *` would publish them.
  * ⛔ THE ADMIN API STAYS ON LOOPBACK OR A UNIX SOCKET. It has no authentication; localCaddyAdmin()
  *   refuses any other address, and a Caddyfile that would move or expose it is refused before load.
- * Guide, order of file and load, `--resume` and secrets: docs/caddy.md.
+ * ⛔ NOTHING IS ADOPTED SILENTLY: a running config that is not the declared one needs `--adopt`.
+ * Guide, order of file and load, adoption, `--resume` and secrets: docs/caddy.md.
  */
 export type {
   CaddyAdmin,

package/src/caddy/providers.test.ts

@@ -3,7 +3,6 @@
  * way the engine calls them; caddyWithFile's registration; and the barrel, the public API.
  */
 import { afterEach, describe, expect, test } from 'bun:test';
-import { Unowned } from 'alchemy/AdoptPolicy';
 import * as Output from 'alchemy/Output';
 import { Stack } from 'alchemy/Stack';
 import * as Effect from 'effect/Effect';
@@ -52,37 +51,23 @@ const withProvider = <A>(
 };
 
 describe('CaddyConfigProvider', () => {
-  test('read with no state ADOPTS: plain attributes of the live config, never Unowned', async () => {
-    const probe = await withProvider((provider) =>
-      handler('read', provider.read)({ ...ids, olds: { caddyfile: SITE }, output: undefined }),
-    );
-    expect(Unowned.is(probe)).toBe(false);
-    expect(probe).toMatchObject({ endpoint: fake?.address });
-  });
-
-  test('reconcile applies; delete then sends nothing at all', async () => {
+  test('reconcile applies over its own state; delete then sends nothing at all', async () => {
     await withProvider((provider) =>
       Effect.gen(function* () {
-        yield* provider.reconcile({
+        const output = yield* provider.reconcile({
           ...ids,
           bindings: [] as never,
           news: { caddyfile: SITE },
-          olds: undefined,
-          output: undefined,
+          olds: { caddyfile: SITE },
+          // ★ State from an earlier deploy: the running `legacy` config is this stack's to replace.
+          output: { configSha256: 'earlier', endpoint: fake?.address ?? '' },
           session: undefined as never,
         });
+        expect(fake?.seen.some((call) => call.path === '/load')).toBe(true);
         const before = fake?.seen.length;
-        const output = yield* handler(
-          'read',
-          provider.read,
-        )({
-          ...ids,
-          olds: { caddyfile: SITE },
-          output: undefined,
-        });
         yield* provider.delete({ ...ids, olds: { caddyfile: SITE }, output } as never);
-        // ★ Only the read above talked to Caddy: delete never unloads, never stops.
-        expect(fake?.seen.length).toBe((before ?? 0) + 1);
+        // ★ Delete never unloads, never stops: not one more call reached Caddy.
+        expect(fake?.seen.length).toBe(before);
       }),
     );
   });

package/src/caddy/with-file.ts

@@ -14,9 +14,13 @@
  *     still an Output, Alchemy skips the adoption probe, and the check runs at apply instead.)
  *   · A Caddyfile that adapts but that Caddy then REFUSES (a port in use, a missing cert file) is
  *     on disk when `/load` fails. Caddy keeps serving the old config, the deploy fails with Caddy's
- *     reason — and a RESTART before the fix would load the refused file. Fix and redeploy, or run
- *     Caddy with `--resume` (docs/caddy.md): it restarts from `autosave.json`, the last config Caddy
- *     ACCEPTED, and the file is only the first-boot fallback.
+ *     reason — and a Caddy started without `--resume` would load the refused file on its next
+ *     restart. Managed Caddies run with `--resume` (decision, 2026-09-21; docs/caddy.md): they
+ *     restart from `autosave.json`, the last config Caddy ACCEPTED, and the file is only the
+ *     first-boot fallback.
+ *   · The skipped probe is also why the ADOPTION check of a first deploy happens at apply: a Caddy
+ *     running a config this stack did not load is refused before `/load` unless the deploy runs
+ *     with `--adopt` (config-lifecycle.ts reconcileConfig) — after this file is written.
  * ⛔ SECRETS ARE REFUSED HERE, AT DECLARATION, before the HostFile exists: its `content` is a prop
  *   too, and would carry a literal into state even if the CaddyConfig then refused it.
  * ★ BOTH RETAIN. Removing this from a stack must not delete the file a restart needs.

package/src/launchd/adopt-apply.test.ts

@@ -0,0 +1,166 @@
+/**
+ * `--adopt` and `adopt(…)` at APPLY, for HostFile and LaunchdJob — the create Alchemy never probed
+ * (a prop still an Output at plan time). Before 2026-09-21 these reconciles refused a foreign file
+ * or job whatever the deploy said, so the flag the refusal told you to use could not work there.
+ * They now resolve adoption the way the planner does (ownership/adopt.ts adoptEnabled), BOTH ways —
+ * for a CREATE only: the row Apply committed for this instance is `creating`. ⛔ A replace's new
+ * generation (a `replacing` row, `output` undefined all the same) is never adoptable at apply.
+ * ★ Registered through the REAL `Resource` under a Stack, as caddy/adopt-scope.test.ts is, over a
+ *   state store holding the row Apply commits before it calls reconcile.
+ */
+import { describe, expect, test } from 'bun:test';
+import { AdoptPolicy, adopt } from 'alchemy/AdoptPolicy';
+import { Artifacts, makeScopedArtifacts } from 'alchemy/Artifacts';
+import { InMemoryService } from 'alchemy/State/InMemoryState';
+import type { ResourceState } from 'alchemy/State/ResourceState';
+import { State } from 'alchemy/State/State';
+import { Stack } from 'alchemy/Stack';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { noteUnfinished } from '../ownership/resume.ts';
+import { fakeRunner } from './fake-runner.ts';
+import { HostFile, HostFileProvider } from './host-file.ts';
+import { LaunchdJob, LaunchdJobProvider } from './job.ts';
+import type { LaunchdJobAttributes } from './job-form.ts';
+import { hostRunnerLayer } from './runner.ts';
+
+type Scope = 'adopt(true)' | 'adopt(false)' | 'none';
+
+const FOREIGN = new TextEncoder().encode('someone else wrote this\n');
+const PATH = '/etc/example/a.conf';
+const PLIST = '/Library/LaunchDaemons/com.example.job.plist';
+const JOB = { domain: 'system', label: 'com.example.job', programArguments: ['/bin/job'] } as const;
+
+const host = () => {
+  const fake = fakeRunner({ dirs: { '/Library/LaunchDaemons': 0, '/etc/example': 0 }, euid: 0 });
+  for (const path of [PATH, PLIST]) {
+    fake.files.set(path, { bytes: FOREIGN, gid: 0, kind: 'file', mode: 0o644, uid: 0 });
+  }
+  return fake;
+};
+
+const scoped = <A extends Effect.Effect<unknown, unknown, unknown>>(declared: A, scope: Scope) =>
+  scope === 'none' ? declared : (declared.pipe(adopt(scope === 'adopt(true)')) as A);
+
+/** The row Apply commits before reconcile: a create's, or a replace's new generation's. */
+type Generation = 'creating' | 'replacing';
+
+/** Register `family` with `scope` under a deploy whose `--adopt` is `flag`; reconcile it statelessly. */
+const firstApply = (
+  family: 'file' | 'job',
+  scope: Scope,
+  flag: boolean,
+  output?: unknown,
+  generation: Generation = 'creating',
+  /** The plan's diff saw this generation's row with no attributes (ownership/resume.ts). */
+  unfinished = false,
+) => {
+  const fake = host();
+  const fqn = family === 'file' ? 'conf' : 'job';
+  const row = { fqn, instanceId: 'i-1', status: generation } as unknown as ResourceState;
+  const spec = { actions: {}, bindings: {}, name: 'test', resources: {}, stage: 'test' };
+  const call = {
+    bindings: [] as never,
+    instanceId: 'i-1',
+    olds: undefined,
+    session: undefined as never,
+  };
+  const program: Effect.Effect<unknown, unknown, AdoptPolicy | Stack> =
+    family === 'file'
+      ? Effect.gen(function* () {
+          yield* scoped(HostFile('conf', { content: 'x', path: PATH }), scope);
+          const provider = yield* HostFile.Provider;
+          const news = { content: 'x', path: PATH };
+          return yield* provider.reconcile({
+            ...call,
+            fqn: 'conf',
+            id: 'conf',
+            news,
+            output: undefined,
+          });
+        }).pipe(
+          Effect.provide(HostFileProvider().pipe(Layer.provide(hostRunnerLayer(fake.runner)))),
+        )
+      : Effect.gen(function* () {
+          yield* scoped(LaunchdJob('job', JOB), scope);
+          const provider = yield* LaunchdJob.Provider;
+          const prior = output as LaunchdJobAttributes | undefined;
+          return yield* provider.reconcile({
+            ...call,
+            fqn: 'job',
+            id: 'job',
+            news: JOB,
+            output: prior,
+          });
+        }).pipe(
+          Effect.provide(LaunchdJobProvider().pipe(Layer.provide(hostRunnerLayer(fake.runner)))),
+        );
+  const bag = makeScopedArtifacts(new Map(), fqn);
+  const noted = unfinished ? noteUnfinished('i-1') : Effect.void;
+  const applying = Effect.runPromise(
+    Effect.andThen(noted, program).pipe(
+      Effect.provideService(Artifacts, bag),
+      Effect.provideService(AdoptPolicy, flag),
+      Effect.provideService(State, InMemoryService({ test: { test: { [fqn]: row } } })),
+      Effect.provideService(Stack, spec as never),
+    ),
+  );
+  return { applying, fake };
+};
+
+const REFUSED = /already exists and is not this resource|is already on this host/;
+
+describe.each(['file', 'job'] as const)('%s: a first apply over a foreign object', (family) => {
+  test.each([
+    ['adopt(false) under --adopt', 'adopt(false)', true, false],
+    ['adopt(true) without --adopt', 'adopt(true)', false, true],
+    ['no scope under --adopt', 'none', true, true],
+    ['no scope without --adopt', 'none', false, false],
+  ] as const)('with %s', async (_, scope, flag, takesOver) => {
+    const { applying, fake } = firstApply(family, scope, flag);
+    const path = family === 'file' ? PATH : PLIST;
+    if (takesOver) {
+      await applying;
+      expect(fake.files.get(path)?.bytes).not.toEqual(FOREIGN);
+    } else {
+      await expect(applying).rejects.toThrow(REFUSED);
+      expect(fake.files.get(path)?.bytes).toEqual(FOREIGN);
+    }
+  });
+});
+
+test('a LaunchdJob rename onto a foreign job stays refused, --adopt or not', async () => {
+  const old = {
+    domain: 'system',
+    label: 'com.example.old',
+    loaded: false,
+    plistPath: '/Library/LaunchDaemons/com.example.old.plist',
+    plistSha256: '',
+    serviceTarget: 'system/com.example.old',
+  };
+  const { applying, fake } = firstApply('job', 'adopt(true)', true, old);
+  await expect(applying).rejects.toThrow(REFUSED);
+  expect(fake.files.get(PLIST)?.bytes).toEqual(FOREIGN);
+});
+
+describe.each(['file', 'job'] as const)('%s: a replace onto a foreign object', (family) => {
+  test.each([
+    ['--adopt', 'none', true],
+    ['adopt(true)', 'adopt(true)', false],
+  ] as const)(
+    'stays refused under %s: the plan never offered its new generation adoption',
+    async (_, scope, flag) => {
+      const { applying, fake } = firstApply(family, scope, flag, undefined, 'replacing');
+      await expect(applying).rejects.toThrow(REFUSED);
+      expect(fake.files.get(family === 'file' ? PATH : PLIST)?.bytes).toEqual(FOREIGN);
+    },
+  );
+
+  test('an UNFINISHED replace (its row seen by the plan) resumes under --adopt, as a create does', async () => {
+    const refused = firstApply(family, 'none', false, undefined, 'replacing', true);
+    await expect(refused.applying).rejects.toThrow(REFUSED);
+    const { applying, fake } = firstApply(family, 'none', true, undefined, 'replacing', true);
+    await applying;
+    expect(fake.files.get(family === 'file' ? PATH : PLIST)?.bytes).not.toEqual(FOREIGN);
+  });
+});

package/src/launchd/fake-runner.ts

@@ -9,6 +9,8 @@
  *   job exits non-zero; a job can linger after bootout (`lingerPrints`); a gui uid with no login
  *   session answers 112 (`loggedOut`); writes into a root-owned directory, or a chown to another
  *   uid, need root.
+ * ★ Every directory ABOVE a declared one exists, root's and `0755`, as `/`, `/Library` and `/opt`
+ *   are on a Mac; `acls` holds the `ls -lden` entry lines a directory prints (sudo-acl.ts).
  */
 import { LAUNCHCTL, NOT_FOUND, NO_DOMAIN } from './launchctl.ts';
 import type { ExecResult, FileStat, HostRunner, HostUser, WriteOptions } from './runner.ts';
@@ -54,6 +56,16 @@ export const fakeRunner = (options: FakeOptions = {}) => {
   const root = privileged || euid === 0;
   const dirs = new Map(Object.entries(options.dirs ?? {}));
   const files = new Map<string, Entry>();
+  /** Directory → the ACL entry lines `ls -lden` prints under it. */
+  const acls = new Map<string, string[]>();
+  /** The directories above the declared ones, as the host starts: root's, `0755`. */
+  const above = new Set<string>(['/']);
+  for (const dir of dirs.keys()) {
+    const parts = dir.split('/').slice(1, -1);
+    for (const index of parts.keys()) above.add(`/${parts.slice(0, index + 1).join('/')}`);
+  }
+  for (const dir of dirs.keys()) above.delete(dir);
+  const implied = (path: string) => above.has(path);
   const calls: string[][] = [];
   /** target → pid (undefined = loaded, not running). */
   const loaded = new Map<string, number | undefined>();
@@ -128,6 +140,16 @@ export const fakeRunner = (options: FakeOptions = {}) => {
     exec: async (argv) => {
       calls.push([...argv]);
       if (argv[0] === LAUNCHCTL) return launchctl(argv.slice(1));
+      if (argv[0] === '/bin/ls' && argv[1] === '-lden' && argv[2] === '--') {
+        const paths = argv.slice(3);
+        if (paths.some((path) => !dirs.has(path) && !files.has(path) && !implied(path)))
+          return fail(1, 'ls: No such file or directory');
+        const lines = paths.flatMap((path) => [
+          `drwxr-xr-x  2 0  0  64 Sep 21 10:00 ${path}`,
+          ...(acls.get(path) ?? []),
+        ]);
+        return ok(lines.join('\n'));
+      }
       return fail(127, `fake: no program ${String(argv[0])}`);
     },
     lookupGroup: async (nameOrId) => options.groups?.[nameOrId],
@@ -153,9 +175,9 @@ export const fakeRunner = (options: FakeOptions = {}) => {
           size: entry.bytes.length,
           uid: entry.uid,
         };
-      return dirs.has(path)
-        ? { gid: 0, kind: 'directory', mode: 0o755, size: 0, uid: dirs.get(path) ?? 0 }
-        : undefined;
+      if (dirs.has(path) || implied(path))
+        return { gid: 0, kind: 'directory', mode: 0o755, size: 0, uid: dirs.get(path) ?? 0 };
+      return undefined;
     },
     writeFileAtomic: async (path: string, bytes: Uint8Array, write: WriteOptions) => {
       calls.push(['write', path]);
@@ -172,5 +194,5 @@ export const fakeRunner = (options: FakeOptions = {}) => {
       });
     },
   };
-  return { calls, disabled, dirs, files, loaded, runner, state };
+  return { acls, calls, disabled, dirs, files, loaded, runner, state };
 };

package/src/launchd/fake-sudo.ts

@@ -0,0 +1,136 @@
+/**
+ * A sudo runner over fake-runner.ts, for the tests beside it: the deploying user is uid 501 and
+ * unprivileged, and `/usr/bin/sudo` is a tiny interpreter that runs the three allowlisted programs
+ * against the same in-memory host, as root.
+ *
+ * ⛔ TEST-ONLY, like fake-runner.ts: no provider imports it, it is not on the barrel, and it never
+ *   runs a real program. No test anywhere runs a real sudo.
+ * ★ THE INTERPRETER READS ONLY WHAT THE ARGV SAYS — mode, owner, group, source, destination — so a
+ *   runner that dropped `-o` or wrote the wrong path shows up as the wrong file, not a passing test.
+ * ★ THE BASE STAYS UNPRIVILEGED, so a write under /Library/LaunchDaemons that skipped sudo fails
+ *   with the fake's EACCES instead of quietly succeeding.
+ * ★ SUDO REFUSES A CALL THAT WAS NOT LOGGED FIRST, so every test holds the runner to "logged
+ *   before it runs", not merely "logged at some point".
+ */
+import { fakeRunner } from './fake-runner.ts';
+import { LAUNCHCTL } from './launchctl.ts';
+import type { ExecResult, HostRunner } from './runner.ts';
+import { INSTALL, RM, SUDO } from './sudo-allowlist.ts';
+import { makeSudoRunner } from './sudo-runner.ts';
+
+export const OPERATOR = 501;
+export const PREFIXES = ['/Library/LaunchDaemons', '/opt/example'];
+
+const ok: ExecResult = { exitCode: 0, stderr: '', stdout: '' };
+
+/** What `sudo -n` prints (exit 1) when it will not run the command. Reasoned; see sudo-runner.ts. */
+export const SUDO_SAYS = {
+  denied:
+    "Sorry, user someone is not allowed to execute '/bin/launchctl bootout system/x' as root on example.\n",
+  'not-in-sudoers': 'someone is not in the sudoers file.\n',
+  'not-on-host': 'someone is not allowed to run sudo on example.\n',
+  password: 'sudo: a password is required\n',
+} as const;
+const fail = (exitCode: number, stderr: string): ExecResult => ({ exitCode, stderr, stdout: '' });
+
+/** Parse `install -S -m MODE [-o UID] [-g GID] SRC DEST` the way install(1) would. */
+const parseInstall = (args: readonly string[]) => {
+  const mode = Number.parseInt(args[2] ?? '', 8);
+  const rest = args.slice(3);
+  const flag = (name: string) => {
+    const at = rest.indexOf(name);
+    return at === -1 ? undefined : Number(rest[at + 1]);
+  };
+  return {
+    dest: rest[rest.length - 1] ?? '',
+    gid: flag('-g'),
+    mode,
+    source: rest[rest.length - 2] ?? '',
+    uid: flag('-o'),
+  };
+};
+
+/** `groups` is the operator's `id -G`; `'unknown'` models that lookup failing. */
+export const fakeSudoHost = (
+  groups: readonly number[] | 'unknown' = [20, 80],
+  prefixes: readonly string[] = PREFIXES,
+) => {
+  const fake = fakeRunner({
+    dirs: {
+      '/Library/LaunchDaemons': 0,
+      '/opt/example': 0,
+      '/opt/example/app': 0,
+      '/Users/someone/Library/LaunchAgents': OPERATOR,
+      '/Users/other/Library/LaunchAgents': 502,
+      // Root-owned, and deliberately NOT a prefix: the forgotten-prefix case.
+      '/etc/example': 0,
+    },
+    euid: OPERATOR,
+    users: {
+      other: { gid: 20, home: '/Users/other', uid: 502 },
+      someone: { gid: 20, home: '/Users/someone', uid: OPERATOR },
+    },
+  });
+  const staged = new Map<string, Uint8Array>();
+  const logs: string[] = [];
+  const sudoCalls: string[][] = [];
+  const state = {
+    /** What sudo itself answers: runs the command, or refuses it with one of SUDO_SAYS. */
+    sudo: 'ok' as 'ok' | keyof typeof SUDO_SAYS,
+    /** Returned by `install` in place of success; nothing is written. */
+    installFailure: undefined as ExecResult | undefined,
+    stagedCount: 0,
+    /** The staged bytes as `install` saw them, by destination. */
+    installedFrom: new Map<string, string>(),
+  };
+
+  const asRoot = async (argv: readonly string[]): Promise<ExecResult> => {
+    const [program, ...args] = argv;
+    if (program === LAUNCHCTL) return fake.runner.exec(argv);
+    if (program === INSTALL) {
+      if (state.installFailure !== undefined) return state.installFailure;
+      const { dest, gid, mode, source, uid } = parseInstall(args);
+      const bytes = staged.get(source);
+      if (bytes === undefined) return fail(71, `install: ${source}: No such file or directory`);
+      state.installedFrom.set(dest, new TextDecoder().decode(bytes));
+      // ★ No -g: the new file takes its directory's group, as a BSD file create does.
+      const dirGid = (await fake.runner.stat(dest.slice(0, dest.lastIndexOf('/'))))?.gid ?? 0;
+      fake.files.set(dest, { bytes, gid: gid ?? dirGid, kind: 'file', mode, uid: uid ?? 0 });
+      return ok;
+    }
+    if (program === RM) {
+      fake.files.delete(args[2] ?? '');
+      return ok;
+    }
+    return fail(1, `sudo: ${String(program)}: command not found`);
+  };
+
+  const base: HostRunner = {
+    ...fake.runner,
+    exec: async (argv) => {
+      if (argv[0] !== SUDO) return fake.runner.exec(argv);
+      sudoCalls.push([...argv]);
+      if (logs[logs.length - 1] !== `homeflare/launchd sudo -n ${JSON.stringify(argv.slice(3))}`) {
+        throw new Error(`fake sudo: ${JSON.stringify(argv)} was not logged before it ran`);
+      }
+      if (state.sudo !== 'ok') return fail(1, SUDO_SAYS[state.sudo]);
+      // argv is [sudo, -n, --, ...command]
+      return asRoot(argv.slice(3));
+    },
+  };
+
+  const runner = makeSudoRunner(prefixes, {
+    base,
+    groups: async () => (groups === 'unknown' ? undefined : groups),
+    log: (line) => logs.push(line),
+    stage: async (bytes) => {
+      state.stagedCount += 1;
+      const path = `/private/tmp/hf-sudo-${String(state.stagedCount)}/staged`;
+      staged.set(path, bytes);
+      return { dispose: async () => void staged.delete(path), path };
+    },
+  });
+  /** The privileged commands run, without the `sudo -n --` in front. */
+  const privileged = () => sudoCalls.map((call) => call.slice(3));
+  return { fake, logs, privileged, runner, staged, state, sudoCalls };
+};

package/src/launchd/host-effect.ts

@@ -1,6 +1,6 @@
 /**
  * The one place a HostRunner's promises become Effects — plus the one probe of an unresolved
- * `news` both providers' diffs share.
+ * `news` both providers' diffs share. (The engine's adopt setting lives in ownership/adopt.ts.)
  *
  * ★ The lifecycle files are plain async functions over a HostRunner (see runner.ts for why the
  *   runner is promise-based), so each provider handler is a single `lift(() => step(runner, …))`.

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

@@ -46,9 +46,12 @@ const identityProblems = (name: string, value: string | number | undefined): str
     : [`${name} ${JSON.stringify(value)} is not a valid user or group name`];
 };
 
-export const fileProblems = (props: HostFileProps): string[] => {
+/**
+ * An absolute, normalised path, or the reasons it is not. ★ Shared with sudo-allowlist.ts, so a
+ *   path the sudo runner may touch as root obeys exactly the rule a declared file does.
+ */
+export const pathProblems = (path: string): 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.
@@ -62,6 +65,11 @@ export const fileProblems = (props: HostFileProps): string[] => {
     found.push('path must be normalised (no trailing slash, no empty, "." or ".." segments)');
   }
   if (path.includes('\x00')) found.push('path contains NUL');
+  return found;
+};
+
+export const fileProblems = (props: HostFileProps): string[] => {
+  const found = pathProblems(props.path);
   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));