@homeflare/alchemy 0.7.0 → 0.10.0

package/dist/launchd/index.js

@@ -1,13 +1,190 @@
 // src/launchd/host-file.ts
 import { Resource } from "alchemy";
-import { Unowned } from "alchemy/AdoptPolicy";
+import { Unowned as Unowned2 } from "alchemy/AdoptPolicy";
 import { isResolved } from "alchemy/Diff";
 import * as Provider from "alchemy/Provider";
+import * as Effect6 from "effect/Effect";
+
+// src/ownership/adopt.ts
+import { AdoptPolicy } from "alchemy/AdoptPolicy";
+import { AlchemyContext } from "alchemy/AlchemyContext";
+import { Stack as Stack3 } from "alchemy/Stack";
+import * as Effect4 from "effect/Effect";
+import * as Option4 from "effect/Option";
+
+// src/ownership/resume.ts
+import { Unowned } from "alchemy/AdoptPolicy";
+import { Artifacts } from "alchemy/Artifacts";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+var PROVEN = "homeflare/ownership/resumes";
+var UNFINISHED = "homeflare/ownership/unfinished";
+var note = (key, instanceId) => Effect.gen(function* () {
+  const bag = yield* Effect.serviceOption(Artifacts);
+  if (Option.isSome(bag))
+    yield* bag.value.set(key, instanceId);
+});
+var noted = (key, instanceId) => Effect.gen(function* () {
+  const bag = yield* Effect.serviceOption(Artifacts);
+  if (Option.isNone(bag))
+    return false;
+  return (yield* bag.value.get(key)) === instanceId;
+});
+var noteUnfinished = (instanceId) => Effect.as(note(UNFINISHED, instanceId), undefined);
+var noteResume = (instanceId, recovered) => Effect.gen(function* () {
+  yield* noteUnfinished(instanceId);
+  const unproven = () => Effect.succeed(undefined);
+  const found = yield* recovered.pipe(Effect.catch(unproven), Effect.catchDefect(unproven));
+  if (found === undefined || found === null || Unowned.is(found))
+    return;
+  yield* note(PROVEN, instanceId);
+});
+var resumes = (instanceId) => noted(PROVEN, instanceId);
+var unfinished = (instanceId) => noted(UNFINISHED, instanceId);
+var provingResumes = (service) => {
+  const { diff, read } = service;
+  if (diff === undefined || read === undefined)
+    return service;
+  const proving = (input) => Effect.gen(function* () {
+    if (input.output === undefined) {
+      yield* noteResume(input.instanceId, read({ ...input, output: undefined }));
+    }
+    return yield* diff(input);
+  });
+  return { ...service, diff: proving };
+};
+
+// src/ownership/rows.ts
+import { Stack as Stack2 } from "alchemy/Stack";
+import { State, isActionState } from "alchemy/State/State";
+import * as Effect3 from "effect/Effect";
+import * as Option3 from "effect/Option";
+
+// src/ownership/whole.ts
+import { Stack } from "alchemy/Stack";
 import * as Effect2 from "effect/Effect";
+import * as Option2 from "effect/Option";
+var absent = (value) => value === undefined || value === null;
+var isPlainObject = (value) => {
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+};
+var carries = (declared, recorded) => {
+  if (absent(declared))
+    return true;
+  if (absent(recorded))
+    return false;
+  if (Array.isArray(declared)) {
+    if (!Array.isArray(recorded))
+      return false;
+    return declared.every((each, index) => carries(each, recorded[index]));
+  }
+  if (isPlainObject(declared)) {
+    if (!isPlainObject(recorded))
+      return false;
+    return Object.entries(declared).every(([key, each]) => carries(each, recorded[key]));
+  }
+  return true;
+};
+var wholeDeclaration = (fqn, props) => Effect2.map(Effect2.serviceOption(Stack), (stack) => {
+  const declared = Option2.isSome(stack) ? stack.value.resources[fqn] : undefined;
+  return declared !== undefined && carries(declared.Props, props);
+});
+
+// src/ownership/rows.ts
+var storeOf = Effect3.gen(function* () {
+  const stack = yield* Effect3.serviceOption(Stack2);
+  const state = yield* Effect3.serviceOption(State);
+  if (Option3.isNone(stack) || Option3.isNone(state))
+    return;
+  const store = yield* state.value;
+  const where = { stack: stack.value.name, stage: stack.value.stage };
+  return { resources: stack.value.resources, store, where };
+});
+var rowAt = (store, where, fqn) => store.get({ ...where, fqn }).pipe(Effect3.orElseSucceed(() => {
+  return;
+}));
+var generationOf = (row, instanceId) => {
+  let at = row;
+  while (typeof at === "object" && at !== null && !isActionState(at)) {
+    const generation = at;
+    if (generation.instanceId === instanceId)
+      return generation;
+    at = generation.old;
+  }
+  return;
+};
+var recordedGeneration = (fqn, instanceId) => Effect3.gen(function* () {
+  const found = yield* storeOf;
+  if (found === undefined)
+    return;
+  for (const at of [fqn, ...found.resources[fqn]?.FormerFqns ?? []]) {
+    const generation = generationOf(yield* rowAt(found.store, found.where, at), instanceId);
+    if (generation !== undefined)
+      return generation;
+  }
+  return;
+});
+var recordedInstance = (fqn, instanceId) => Effect3.gen(function* () {
+  const generation = yield* recordedGeneration(fqn, instanceId);
+  if (generation === undefined)
+    return "absent";
+  return (yield* wholeDeclaration(fqn, generation.props)) ? "whole" : "partial";
+});
+var isCreate = (fqn, instanceId) => Effect3.map(recordedGeneration(fqn, instanceId), (generation) => generation?.status === "creating");
+var forgetRefusedCreate = (fqn, instanceId) => Effect3.gen(function* () {
+  const found = yield* storeOf;
+  if (found === undefined)
+    return;
+  const row = yield* rowAt(found.store, found.where, fqn);
+  const mine = row;
+  if (mine?.status !== "creating" || mine.instanceId !== instanceId || mine.attr !== undefined) {
+    return;
+  }
+  yield* found.store.delete({ ...found.where, fqn }).pipe(Effect3.ignore);
+});
+
+// src/ownership/adopt.ts
+var adoptEnabled = (fqn) => Effect4.gen(function* () {
+  const stack = yield* Effect4.serviceOption(Stack3);
+  const scoped = Option4.isSome(stack) ? stack.value.resources[fqn]?.Adopt : undefined;
+  if (scoped !== undefined)
+    return scoped;
+  const policy = yield* Effect4.serviceOption(AdoptPolicy);
+  if (Option4.isSome(policy))
+    return policy.value;
+  const context = yield* Effect4.serviceOption(AlchemyContext);
+  return Option4.isSome(context) ? context.value.adopt : false;
+});
+var adoptable = (owner) => Effect4.gen(function* () {
+  if (yield* isCreate(owner.fqn, owner.instanceId))
+    return true;
+  return yield* unfinished(owner.instanceId);
+});
+var adoptsAtApply = (owner) => Effect4.gen(function* () {
+  if (!(yield* adoptEnabled(owner.fqn)))
+    return false;
+  return yield* adoptable(owner);
+});
+var refuseTakeover = (owner, what) => Effect4.gen(function* () {
+  if (owner.output !== undefined)
+    return;
+  if (yield* resumes(owner.instanceId))
+    return;
+  const may = yield* adoptable(owner);
+  if (may && (yield* adoptEnabled(owner.fqn)))
+    return;
+  yield* forgetRefusedCreate(owner.fqn, owner.instanceId);
+  const remedy = may ? "Deploy with --adopt (or wrap the resource in adopt(true)) to take it over, or remove it first." : "It is the new identity of a replace, which --adopt does not cover: remove it first.";
+  return yield* Effect4.die(new Error(`${what}: already exists, and this stack holds no state for it — the plan could not ask ` + "first (a prop was still an Output, a replace moved onto it, or it appeared after the " + `plan). Nothing was written. ${remedy}`));
+});
+var claimFor = (owner) => (what) => refuseTakeover(owner, what);
 
 // src/launchd/host-effect.ts
-import * as Effect from "effect/Effect";
-var lift = (step) => Effect.tryPromise({
+import * as Effect5 from "effect/Effect";
+var lift = (step) => Effect5.tryPromise({
   catch: (cause) => cause instanceof Error ? cause : new Error(String(cause)),
   try: step
 });
@@ -69,9 +246,8 @@ var identityProblems = (name, value) => {
   }
   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`];
 };
-var fileProblems = (props) => {
+var pathProblems = (path) => {
   const found = [];
-  const { path } = props;
   if (!path.startsWith("/"))
     found.push("path must be absolute");
   if (path.endsWith("/") || path.split("/").slice(1).some((part) => part === "" || part === "." || part === "..")) {
@@ -79,6 +255,10 @@ var fileProblems = (props) => {
   }
   if (path.includes("\x00"))
     found.push("path contains NUL");
+  return found;
+};
+var fileProblems = (props) => {
+  const found = pathProblems(props.path);
   const mode = props.mode ?? DEFAULT_MODE;
   if (!Number.isSafeInteger(mode) || mode < 0 || mode > 4095)
     found.push("mode must be 0–0o7777");
@@ -114,7 +294,7 @@ var escapeText = (text, path) => {
   }
   return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\r", "&#13;");
 };
-var isPlainObject = (value) => {
+var isPlainObject2 = (value) => {
   const proto = Object.getPrototypeOf(value);
   return proto === Object.prototype || proto === null;
 };
@@ -149,7 +329,7 @@ var renderValue = (value, path, depth, out) => {
     out.push(`${pad}</array>`);
     return;
   }
-  if (typeof value === "object" && value !== null && isPlainObject(value)) {
+  if (typeof value === "object" && value !== null && isPlainObject2(value)) {
     renderDict(value, path, depth, out);
     return;
   }
@@ -172,7 +352,7 @@ var renderDict = (dict, path, depth, out) => {
   out.push(`${pad}</dict>`);
 };
 var renderPlist = (dict) => {
-  if (typeof dict !== "object" || dict === null || Array.isArray(dict) || !isPlainObject(dict)) {
+  if (typeof dict !== "object" || dict === null || Array.isArray(dict) || !isPlainObject2(dict)) {
     throw new PlistError("", "the top level of a launchd plist must be a dict");
   }
   const out = [];
@@ -328,20 +508,29 @@ var readFileAttributes = async (runner, path) => {
     uid: stat.uid
   };
 };
+var writeOptionsOf = (want) => ({
+  mode: want.mode,
+  ...want.uid === undefined ? {} : { uid: want.uid },
+  ...want.gid === undefined ? {} : { gid: want.gid }
+});
 var matches = (live, want) => live.sha256 === want.sha256 && live.mode === want.mode && (want.uid === undefined || live.uid === want.uid) && (want.gid === undefined || live.gid === want.gid);
 var diffFile = async (runner, news, output) => {
-  if (news.path !== output.path)
-    return { action: "replace" };
   const want = await desiredFile(runner, news);
+  const writes = async (diff) => {
+    await runner.checkWrite?.(news.path, writeOptionsOf(want));
+    return diff;
+  };
+  if (news.path !== output.path)
+    return writes({ action: "replace" });
   if (want.sha256 !== output.sha256)
-    return { action: "update" };
+    return writes({ action: "update" });
   const live = await readFileAttributes(runner, news.path);
-  return live !== undefined && matches(live, want) ? { action: "noop" } : { action: "update" };
+  return live !== undefined && matches(live, want) ? { action: "noop" } : writes({ action: "update" });
 };
-var reconcileFile = async (runner, props, output) => {
+var reconcileFile = async (runner, props, output, adopt = false) => {
   const want = await desiredFile(runner, props);
   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.");
+    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 (sudoRunner() with this path under a prefix). This " + "provider never calls sudo itself.");
   }
   const stat = await runner.stat(props.path);
   if (stat !== undefined && stat.kind !== "file") {
@@ -350,15 +539,12 @@ var reconcileFile = async (runner, props, output) => {
   const before = stat === undefined ? undefined : await readFileAttributes(runner, props.path);
   const moved = output !== undefined && output.path !== props.path;
   const prior = moved ? undefined : output;
-  if (prior === undefined && before !== undefined && !matches(before, want)) {
+  const takeOver = adopt && output === undefined;
+  if (prior === undefined && before !== undefined && !matches(before, want) && !takeOver) {
     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 }
-    });
+    await runner.writeFileAtomic(props.path, want.bytes, writeOptionsOf(want));
   }
   const after = await readFileAttributes(runner, props.path);
   if (after === undefined || !matches(after, want)) {
@@ -383,34 +569,34 @@ var deleteFile = async (runner, output) => {
 
 // src/launchd/host-file.ts
 var HostFile = Resource("Host.File");
-var HostFileProvider = () => Provider.effect(HostFile, Effect2.gen(function* () {
+var HostFileProvider = () => Provider.effect(HostFile, Effect6.gen(function* () {
   const runner = yield* HostRunnerService;
   return HostFile.Provider.of({
-    list: () => Effect2.succeed([]),
+    list: () => Effect6.succeed([]),
     read: ({ olds, output }) => lift(async () => {
       const found = await readFileAttributes(runner, olds.path);
       if (found === undefined)
         return;
-      return output === undefined ? Unowned(found) : found;
+      return output === undefined ? Unowned2(found) : found;
     }),
-    diff: ({ news, output }) => {
+    diff: ({ instanceId, news, output }) => {
       if (output === undefined)
-        return Effect2.succeed(undefined);
+        return noteUnfinished(instanceId);
       if (isResolved(news))
         return lift(() => diffFile(runner, news, output));
       const path = resolvedString(news, "path");
-      return Effect2.succeed(path !== undefined && path !== output.path ? { action: "replace" } : undefined);
+      return Effect6.succeed(path !== undefined && path !== output.path ? { action: "replace" } : undefined);
     },
-    reconcile: ({ news, output }) => lift(() => reconcileFile(runner, news, output)),
+    reconcile: ({ fqn, instanceId, news, output }) => Effect6.flatMap(adoptsAtApply({ fqn, instanceId, output }), (adopt) => lift(() => reconcileFile(runner, news, output, adopt))),
     delete: ({ output }) => lift(() => deleteFile(runner, output))
   });
 }));
 // src/launchd/job.ts
 import { Resource as Resource2 } from "alchemy";
-import { Unowned as Unowned2 } from "alchemy/AdoptPolicy";
+import { Unowned as Unowned3 } from "alchemy/AdoptPolicy";
 import { isResolved as isResolved2 } from "alchemy/Diff";
 import * as Provider2 from "alchemy/Provider";
-import * as Effect3 from "effect/Effect";
+import * as Effect7 from "effect/Effect";
 
 // src/launchd/job-validate.ts
 var LABEL = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/;
@@ -605,6 +791,8 @@ var bootoutIfLoaded = async (runner, target) => {
 };
 
 // src/launchd/job-preflight.ts
+var plistWriteOptions = (domain) => domain.kind === "system" ? { gid: 0, mode: 420, uid: 0 } : { mode: 420, uid: domain.uid };
+var checkPlistWrite = async (runner, location) => runner.checkWrite?.(location.plistPath, plistWriteOptions(location.domain));
 var refuse2 = (label, message) => new Error(`Launchd.Job ${label}: ${message}`);
 var assertValid = (props) => {
   const found = jobProblems(props);
@@ -626,7 +814,7 @@ var assertMayWrite = (runner, label, domain) => {
   if (canActAsRoot(runner))
     return;
   if (domain.kind === "system") {
-    throw refuse2(label, "the system domain needs root. Run the deploy as root, or provide a HostRunner that is " + "deliberately privileged (privileged: true). This provider never calls sudo.");
+    throw refuse2(label, "the system domain needs root. Run the deploy as root, or pass a deliberately privileged " + "HostRunner: sudoRunner() elevates exactly the calls this needs. This provider never " + "calls sudo itself.");
   }
   if (domain.uid !== runner.effectiveUid()) {
     throw refuse2(label, `gui/${String(domain.uid)} belongs to another user; only root may write it. ` + "Deploy as that user, as root, or through a privileged HostRunner.");
@@ -661,6 +849,7 @@ var assertReplaceable = async (runner, next, full, old, renderedSha256) => {
   assertMayWrite(runner, old.label, oldDomain);
   const { location, status } = await preflight(runner, next);
   await assertUnclaimed(runner, next.label, location, status, renderedSha256);
+  await checkPlistWrite(runner, location);
 };
 
 // src/launchd/job-lifecycle.ts
@@ -696,20 +885,24 @@ var diffJob = async (runner, news, output) => {
   }
   assertValid(news);
   const desired = renderJob(news).sha256;
-  if (desired !== output.plistSha256)
+  const update = async () => {
+    await checkPlistWrite(runner, await locate(runner, news));
     return { action: "update" };
+  };
+  if (desired !== output.plistSha256)
+    return update();
   const live = await readJob(runner, news);
   if (live === undefined || !live.loaded || live.plistSha256 !== desired)
-    return { action: "update" };
+    return update();
   return { action: "noop" };
 };
-var reconcileJob = async (runner, props, output) => {
+var reconcileJob = async (runner, props, output, adopt = false) => {
   assertValid(props);
   const { location, status } = await preflight(runner, props);
   const rendered = renderJob(props);
   const renamed = output !== undefined && (output.label !== props.label || output.domain !== props.domain);
   const prior = renamed ? undefined : output;
-  if (prior === undefined) {
+  if (prior === undefined && !(adopt && output === undefined)) {
     await assertUnclaimed(runner, props.label, location, status, rendered.sha256);
   }
   if (renamed)
@@ -718,7 +911,7 @@ var reconcileJob = async (runner, props, output) => {
   if (status.loaded && before !== undefined && sha256Hex(before) === rendered.sha256 && prior?.plistSha256 === rendered.sha256) {
     return attributesOf(props, location, rendered.sha256, status);
   }
-  await runner.writeFileAtomic(location.plistPath, rendered.bytes, location.domain.kind === "system" ? { gid: 0, mode: 420, uid: 0 } : { mode: 420, uid: location.domain.uid });
+  await runner.writeFileAtomic(location.plistPath, rendered.bytes, plistWriteOptions(location.domain));
   await bootoutIfLoaded(runner, location.target);
   const failed = async (detail) => {
     const removed = before === undefined && await runner.removeFile(location.plistPath).then(() => true, () => false);
@@ -745,26 +938,26 @@ var deleteJob = async (runner, output) => {
 
 // src/launchd/job.ts
 var LaunchdJob = Resource2("Launchd.Job");
-var LaunchdJobProvider = () => Provider2.effect(LaunchdJob, Effect3.gen(function* () {
+var LaunchdJobProvider = () => Provider2.effect(LaunchdJob, Effect7.gen(function* () {
   const runner = yield* HostRunnerService;
   return LaunchdJob.Provider.of({
-    list: () => Effect3.succeed([]),
+    list: () => Effect7.succeed([]),
     read: ({ olds, output }) => lift(async () => {
       const found = await readJob(runner, olds);
       if (found === undefined)
         return;
-      return output === undefined ? Unowned2(found) : found;
+      return output === undefined ? Unowned3(found) : found;
     }),
-    diff: ({ news, output }) => {
+    diff: ({ instanceId, news, output }) => {
       if (output === undefined)
-        return Effect3.succeed(undefined);
+        return noteUnfinished(instanceId);
       if (isResolved2(news))
         return lift(() => diffJob(runner, news, output));
       const label = resolvedString(news, "label");
       const domain = resolvedString(news, "domain");
-      return label !== undefined && domain !== undefined && (label !== output.label || domain !== output.domain) ? lift(() => replaceDiff(runner, { domain, label }, undefined, output)) : Effect3.succeed(undefined);
+      return label !== undefined && domain !== undefined && (label !== output.label || domain !== output.domain) ? lift(() => replaceDiff(runner, { domain, label }, undefined, output)) : Effect7.succeed(undefined);
     },
-    reconcile: ({ news, output }) => lift(() => reconcileJob(runner, news, output)),
+    reconcile: ({ fqn, instanceId, news, output }) => Effect7.flatMap(adoptsAtApply({ fqn, instanceId, output }), (adopt) => lift(() => reconcileJob(runner, news, output, adopt))),
     delete: ({ output }) => lift(() => deleteJob(runner, output))
   });
 }));
@@ -835,8 +1028,8 @@ var parseGroup = (platform, stdout) => {
 };
 
 // src/launchd/local-runner.ts
-var code = (cause) => typeof cause === "object" && cause !== null && ("code" in cause) ? String(cause.code) : undefined;
-var absent = (cause) => code(cause) === "ENOENT" || code(cause) === "ENOTDIR";
+var errnoCode = (cause) => typeof cause === "object" && cause !== null && ("code" in cause) ? String(cause.code) : undefined;
+var absent2 = (cause) => errnoCode(cause) === "ENOENT" || errnoCode(cause) === "ENOTDIR";
 var run = (argv, timeoutMs) => new Promise((resolve, reject) => {
   const [program, ...args] = argv;
   if (program === undefined) {
@@ -915,7 +1108,7 @@ var localRunner = (options = {}) => {
       try {
         return new Uint8Array(await readFile(path));
       } catch (cause) {
-        if (absent(cause))
+        if (absent2(cause))
           return;
         throw cause;
       }
@@ -924,7 +1117,7 @@ var localRunner = (options = {}) => {
       try {
         await unlink(path);
       } catch (cause) {
-        if (!absent(cause))
+        if (!absent2(cause))
           throw cause;
       }
     },
@@ -940,7 +1133,7 @@ var localRunner = (options = {}) => {
           uid: stats.uid
         };
       } catch (cause) {
-        if (absent(cause))
+        if (absent2(cause))
           return;
         throw cause;
       }
@@ -951,6 +1144,404 @@ var localRunner = (options = {}) => {
 // src/launchd/providers.ts
 import * as Layer2 from "effect/Layer";
 var launchdProviders = (runner = localRunner()) => Layer2.mergeAll(LaunchdJobProvider(), HostFileProvider()).pipe(Layer2.provide(hostRunnerLayer(runner)));
+// src/launchd/sudo-allowlist.ts
+class SudoRefusedError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SudoRefusedError";
+  }
+}
+var SUDO = "/usr/bin/sudo";
+var INSTALL = "/usr/bin/install";
+var RM = "/bin/rm";
+var WRITES = new Set(["bootstrap", "bootout", "kickstart"]);
+var octalMode = (mode) => Number.isSafeInteger(mode) && mode >= 0 && mode <= 4095 ? mode.toString(8).padStart(4, "0") : undefined;
+var checkPrefixes = (prefixes) => {
+  if (prefixes.length === 0) {
+    throw new Error("sudoRunner: no prefixes. Name the directories root may write, e.g. /Library/LaunchDaemons.");
+  }
+  for (const prefix of prefixes) {
+    const found = prefix === "/" ? ['"/" would allow every path'] : pathProblems(prefix);
+    if (found.length > 0) {
+      throw new Error(`sudoRunner: prefix ${JSON.stringify(prefix)}: ${found.join("; ")}`);
+    }
+  }
+  return [...prefixes];
+};
+var prefixOf = (path, prefixes) => pathProblems(path).length > 0 ? undefined : prefixes.find((prefix) => path.startsWith(`${prefix}/`));
+var labelOk = (label) => LABEL.test(label) && !RESERVED_LABEL_PREFIXES.some((prefix) => label.startsWith(prefix));
+var systemLabel = (target) => {
+  const label = target?.startsWith("system/") === true ? target.slice("system/".length) : undefined;
+  return label !== undefined && labelOk(label) ? label : undefined;
+};
+var daemonPlist = (label, prefixes) => {
+  const path = plistPathFor(label, { kind: "system" }, undefined);
+  return prefixOf(path, prefixes) === undefined ? undefined : path;
+};
+var NO_DAEMON_PREFIX = "needs /Library/LaunchDaemons among the prefixes, where the job’s plist is written and removed";
+var launchctlProblem = (args, prefixes) => {
+  const [sub, ...rest] = args;
+  if (sub === "bootstrap") {
+    const given = rest[1] ?? "";
+    const name = given.slice(given.lastIndexOf("/") + 1);
+    const label = name.endsWith(".plist") ? name.slice(0, -".plist".length) : "";
+    const shaped = rest.length === 2 && rest[0] === "system" && labelOk(label);
+    if (!shaped)
+      return "bootstrap takes exactly `system /Library/LaunchDaemons/<label>.plist`";
+    const plist = daemonPlist(label, prefixes);
+    if (plist === undefined)
+      return `bootstrap ${NO_DAEMON_PREFIX}`;
+    return given === plist ? undefined : `bootstrap loads only ${plist}, never another path`;
+  }
+  if (sub === "bootout") {
+    const label = rest.length === 1 ? systemLabel(rest[0]) : undefined;
+    if (label === undefined)
+      return "bootout takes exactly `system/<label>`, never a bare domain";
+    return daemonPlist(label, prefixes) === undefined ? `bootout ${NO_DAEMON_PREFIX}` : undefined;
+  }
+  if (sub === "kickstart") {
+    const flags = rest.slice(0, -1);
+    const flagsOk = flags.every((flag) => flag === "-k" || flag === "-p") && new Set(flags).size === flags.length;
+    return flagsOk && systemLabel(rest[rest.length - 1]) !== undefined ? undefined : "kickstart takes only -k / -p, then `system/<label>`";
+  }
+  return `launchctl ${String(sub)} is never run as root`;
+};
+var ID = /^\d+$/;
+var idsOk = (ids) => {
+  const [flag, id, second, secondId] = ids;
+  if (ids.length === 0)
+    return true;
+  if (ids.length === 2)
+    return (flag === "-o" || flag === "-g") && ID.test(id ?? "");
+  return ids.length === 4 && flag === "-o" && ID.test(id ?? "") && second === "-g" && ID.test(secondId ?? "");
+};
+var privilegedProblem = (argv, context) => {
+  const [program, ...args] = argv;
+  const under = (path) => path !== undefined && prefixOf(path, context.prefixes) !== undefined;
+  if (program === LAUNCHCTL)
+    return launchctlProblem(args, context.prefixes);
+  if (program === INSTALL) {
+    const [safe, m, mode, ...rest] = args;
+    if (safe !== "-S" || m !== "-m" || mode === undefined || !/^[0-7]{4}$/.test(mode)) {
+      return "install takes exactly `-S -m <4 octal digits> [-o <uid>] [-g <gid>] <staged> <dest>`";
+    }
+    if (rest.length < 2 || !idsOk(rest.slice(0, -2)))
+      return "install takes only -o <uid> -g <gid>";
+    const [source, dest] = rest.slice(-2);
+    if (source === undefined || source !== context.staged) {
+      return "install copies only the file this runner staged";
+    }
+    return under(dest) ? undefined : "install destination is not under a declared prefix";
+  }
+  if (program === RM) {
+    const [force, end, path, ...extra] = args;
+    return force === "-f" && end === "--" && extra.length === 0 && under(path) ? undefined : "rm takes exactly `-f -- <path under a declared prefix>`";
+  }
+  return `${String(program)} is not on the sudo allowlist`;
+};
+var routeExec = (argv, operatorUid) => {
+  const [program, sub] = argv;
+  if (program === "sudo" || program?.endsWith("/sudo") === true) {
+    return {
+      refuse: "sudoRunner never passes a sudo argv through; it elevates only its allowlist"
+    };
+  }
+  if (program !== LAUNCHCTL || sub === undefined || !WRITES.has(sub))
+    return { as: "operator" };
+  const target = sub === "kickstart" ? argv[argv.length - 1] : argv[2];
+  if (target === "system" || target?.startsWith("system/") === true)
+    return { as: "root" };
+  const owner = /^(?:gui|user)\/(\d+)(?:\/|$)/.exec(target ?? "")?.[1];
+  if (owner === undefined || Number(owner) === operatorUid)
+    return { as: "operator" };
+  return {
+    refuse: `launchctl ${sub} ${String(target)}: that domain belongs to uid ${owner}, and sudoRunner ` + "elevates only the system domain. Deploy as that user, or as root."
+  };
+};
+
+// src/launchd/sudo-acl.ts
+var LS = "/bin/ls";
+var WRITE_RIGHTS = new Set([
+  "add_file",
+  "add_subdirectory",
+  "append",
+  "chown",
+  "delete",
+  "delete_child",
+  "write",
+  "writesecurity"
+]);
+var ENTRY = /^\s*\d+:\s+\S+\s+(?:inherited\s+)?allow\s+(\S+)/;
+var aclGrants = (listing) => listing.split(`
+`).filter((line) => {
+  const rights = ENTRY.exec(line)?.[1];
+  return rights !== undefined && rights.split(",").some((right) => WRITE_RIGHTS.has(right));
+}).map((line) => line.trim());
+var assertNoAclGrants = async (base, path, chain) => {
+  const listed = await base.exec([LS, "-lden", "--", ...chain]);
+  if (listed.exitCode !== 0) {
+    throw new SudoRefusedError(`sudoRunner ${path}: could not read the ACLs of the directories from / down to it ` + `(${LS} -lden exit ${String(listed.exitCode)}). Nothing ran as root.`);
+  }
+  const grants = aclGrants(listed.stdout);
+  if (grants.length === 0)
+    return;
+  throw new SudoRefusedError(`sudoRunner ${path}: a directory from / down to it carries an ACL that lets someone other ` + `than root change what it holds (${grants.join("; ")}). Remove the entry (chmod -a), or ` + "declare a prefix without one. Nothing ran as root.");
+};
+
+// src/launchd/sudo-guard.ts
+var refuse3 = (path, message) => new SudoRefusedError(`sudoRunner ${path}: ${message}`);
+var betweenDirs = (prefix, path) => {
+  const parts = path.slice(prefix.length + 1).split("/").slice(0, -1);
+  return parts.map((_, index) => `${prefix}/${parts.slice(0, index + 1).join("/")}`);
+};
+var aboveDirs = (prefix) => {
+  const parts = prefix.split("/").slice(1, -1);
+  return ["/", ...parts.map((_, index) => `/${parts.slice(0, index + 1).join("/")}`)];
+};
+var rootOnlyProblem = (stat) => {
+  if (stat === undefined)
+    return "is missing";
+  if (stat.kind !== "directory")
+    return `is a ${stat.kind}, not a directory`;
+  if (stat.uid !== 0)
+    return `is owned by uid ${String(stat.uid)}, not root`;
+  if ((stat.mode & 18) !== 0) {
+    return `is writable by group or other (mode ${stat.mode.toString(8).padStart(4, "0")})`;
+  }
+  return;
+};
+var assertPlainPath = async (base, prefix, path, expect) => {
+  const above = aboveDirs(prefix);
+  for (const [index, stat] of (await Promise.all(above.map((dir) => base.stat(dir)))).entries()) {
+    const up = stat?.kind === "symlink" && stat.uid === 0 ? undefined : rootOnlyProblem(stat);
+    if (up !== undefined) {
+      throw refuse3(path, `${String(above[index])}, above the declared prefix ${prefix}, ${up}. Whoever may change it ` + "may swap the prefix itself; every directory from / down must be root-only. Nothing ran as root.");
+    }
+  }
+  const dirs = betweenDirs(prefix, path);
+  const [prefixStat, ...stats] = await Promise.all([prefix, ...dirs].map((dir) => base.stat(dir)));
+  const bad = rootOnlyProblem(prefixStat);
+  if (bad !== undefined) {
+    throw refuse3(path, `the declared prefix ${prefix} ${bad}. Declare only a real directory that root owns and ` + "only root may write. Nothing ran as root.");
+  }
+  for (const [index, stat] of stats.entries()) {
+    const dir = String(dirs[index]);
+    if (stat?.kind !== "directory") {
+      throw refuse3(path, `${dir} is ${stat === undefined ? "missing" : `a ${stat.kind}`}; root ` + "writes only through real directories under a declared prefix.");
+    }
+    const below = rootOnlyProblem(stat);
+    if (below !== undefined) {
+      throw refuse3(path, `${dir} ${below}. Every directory from the prefix ${prefix} down to the file must be one ` + "that root owns and only root may write. Nothing ran as root.");
+    }
+  }
+  await assertNoAclGrants(base, path, [...above, prefix, ...dirs]);
+  const target = await base.stat(path);
+  if (target === undefined && expect === "file-or-absent")
+    return "absent";
+  if (target?.kind === "file")
+    return "file";
+  throw refuse3(path, `is ${target === undefined ? "missing" : `a ${target.kind}`}, not a file`);
+};
+var modeProblem = (options) => {
+  if (options.uid !== undefined && options.uid !== 0)
+    return;
+  const found = [];
+  if ((options.mode & 3072) !== 0)
+    found.push("setuid/setgid");
+  if ((options.mode & 18) !== 0)
+    found.push("writable by group or other");
+  if (found.length === 0)
+    return;
+  return `mode ${options.mode.toString(8).padStart(4, "0")} is ${found.join(" and ")} on a root-owned file`;
+};
+var assertInstallable = async (base, prefix, path, options, groups) => {
+  const mode = modeProblem(options);
+  if (mode !== undefined) {
+    throw refuse3(path, `${mode}. Declare a mode without those bits (0644, 0640, 0755), or give the file to its ` + "real owner. Nothing ran as root.");
+  }
+  await assertPlainPath(base, prefix, path, "file-or-absent");
+  await assertReadableBack(base, path, options, groups);
+};
+var canRead = (file, uid, groups) => {
+  if (uid === 0)
+    return true;
+  if (file.uid === uid)
+    return (file.mode & 256) !== 0;
+  const groupRead = (file.mode & 32) !== 0;
+  const otherRead = (file.mode & 4) !== 0;
+  if (groupRead === otherRead)
+    return groupRead;
+  if (groups === undefined)
+    return;
+  return groups.includes(file.gid) ? groupRead : otherRead;
+};
+var assertReadableBack = async (base, path, options, groups) => {
+  const operator = base.effectiveUid();
+  const parent = path.slice(0, path.lastIndexOf("/")) || "/";
+  const gid = options.gid ?? (await base.stat(parent))?.gid ?? 0;
+  const file = { gid, mode: options.mode, uid: options.uid ?? 0 };
+  if (canRead(file, operator, groups) !== false)
+    return;
+  throw refuse3(path, `owner ${String(file.uid)}, group ${String(gid)}, mode ${file.mode.toString(8)} would hide it ` + `from the deploying user (uid ${String(operator)}), who reads every file back. Declare a ` + "mode that user can read, or deploy as root. Nothing was written.");
+};
+var operatorGroups = async (base) => {
+  const result = await base.exec(["/usr/bin/id", "-G"]);
+  const ids = result.stdout.trim().split(/\s+/);
+  return result.exitCode === 0 && ids.every((id) => /^\d+$/.test(id)) ? ids.map(Number) : undefined;
+};
+
+// src/launchd/sudo-said.ts
+var PASSWORD = /^sudo: (?:a password is required|a terminal is required|sorry, you must have a tty)/m;
+var NOT_ALLOWED = /^(?:Sorry, user \S+ (?:is not allowed to execute|may not run sudo)|\S+ is not (?:in the sudoers file|allowed to run sudo on ))/m;
+var undeclared = (path, prefixes) => (cause) => {
+  const code = errnoCode(cause);
+  if (code !== "EACCES" && code !== "EPERM")
+    throw cause;
+  throw new Error(`sudoRunner ${path}: ${code} as the deploying user, and the path is under no declared prefix ` + `(${prefixes.join(", ")}). If root owns its directory, declare that directory as a prefix.`, { cause });
+};
+var sudoRefusal = (shown, result) => {
+  if (result.exitCode !== 1)
+    return;
+  if (PASSWORD.test(result.stderr)) {
+    return new SudoRefusedError(`sudo -n ${shown}: a password is required, and this runner never prompts. Run \`sudo -v\` ` + "in the deploying terminal just before the deploy, or grant exactly these commands " + "NOPASSWD (docs/launchd-sudo.md). The command did not run.");
+  }
+  if (NOT_ALLOWED.test(result.stderr)) {
+    return new SudoRefusedError(`sudo -n ${shown}: sudoers does not let the deploying user run this. The command did not run.`);
+  }
+  return;
+};
+
+// src/launchd/sudo-stage.ts
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join as join2 } from "node:path";
+var stageFile = async (bytes) => {
+  const dir = await mkdtemp(join2(tmpdir(), "hf-sudo-"));
+  const dispose = () => rm(dir, { force: true, recursive: true });
+  try {
+    const path = join2(dir, "staged");
+    await writeFile(path, bytes, { flag: "wx", mode: 384 });
+    return { dispose, path };
+  } catch (cause) {
+    await dispose();
+    throw cause;
+  }
+};
+
+// src/launchd/sudo-runner.ts
+var makeSudoRunner = (prefixList, deps) => {
+  const prefixes = checkPrefixes(prefixList);
+  const { base } = deps;
+  const elevate = async (argv, { before, staged } = {}) => {
+    const shown = JSON.stringify(argv);
+    const problem = privilegedProblem(argv, {
+      prefixes,
+      ...staged === undefined ? {} : { staged }
+    });
+    if (problem !== undefined)
+      throw new SudoRefusedError(`sudoRunner refused ${shown}: ${problem}`);
+    await before?.();
+    deps.log(`homeflare/launchd sudo -n ${shown}`);
+    const result = await base.exec([SUDO, "-n", "--", ...argv]);
+    const refused = sudoRefusal(shown, result);
+    if (refused !== undefined)
+      throw refused;
+    return result;
+  };
+  const vetWrite = async (path, options) => {
+    const prefix = prefixOf(path, prefixes);
+    const operator = base.effectiveUid();
+    if (prefix === undefined) {
+      if (options.uid !== undefined && options.uid !== operator && operator !== 0) {
+        throw new SudoRefusedError(`sudoRunner ${path}: owner ${String(options.uid)} needs root, and the path is under no ` + `declared prefix (${prefixes.join(", ")}). Declare its directory, or deploy as root. ` + "Nothing was written.");
+      }
+      return;
+    }
+    const mode = octalMode(options.mode);
+    if (mode === undefined)
+      throw new SudoRefusedError(`sudoRunner ${path}: mode must be 0–0o7777`);
+    await assertInstallable(base, prefix, path, options, await deps.groups());
+    return { mode, prefix };
+  };
+  const mustSucceed = async (argv, staged) => {
+    const result = await elevate(argv, staged === undefined ? {} : { staged });
+    if (result.exitCode !== 0) {
+      const stderr = result.stderr.trim().slice(0, 300);
+      throw new Error(`sudo -n ${JSON.stringify(argv)} -> ${String(result.exitCode)}: ${stderr}`);
+    }
+  };
+  return {
+    checkWrite: async (path, options) => {
+      await vetWrite(path, options);
+    },
+    effectiveUid: () => base.effectiveUid(),
+    exec: async (argv) => {
+      const route = routeExec(argv, base.effectiveUid());
+      if ("refuse" in route)
+        throw new SudoRefusedError(`sudoRunner: ${route.refuse}`);
+      if (route.as === "operator")
+        return base.exec(argv);
+      const plist = argv[1] === "bootstrap" ? argv[3] : undefined;
+      const prefix = plist === undefined ? undefined : prefixOf(plist, prefixes);
+      return elevate(argv, {
+        before: async () => {
+          if (plist !== undefined && prefix !== undefined) {
+            await assertPlainPath(base, prefix, plist, "file");
+          }
+        }
+      });
+    },
+    lookupGroup: (nameOrId) => base.lookupGroup(nameOrId),
+    lookupUser: (nameOrId) => base.lookupUser(nameOrId),
+    privileged: true,
+    readFile: (path) => base.readFile(path),
+    removeFile: async (path) => {
+      const prefix = prefixOf(path, prefixes);
+      if (prefix === undefined)
+        return base.removeFile(path).catch(undeclared(path, prefixes));
+      if (await base.stat(path) === undefined)
+        return;
+      await assertPlainPath(base, prefix, path, "file");
+      await mustSucceed([RM, "-f", "--", path]);
+    },
+    sleep: (ms) => base.sleep(ms),
+    stat: (path) => base.stat(path),
+    writeFileAtomic: async (path, bytes, options) => {
+      const vetted = await vetWrite(path, options);
+      if (vetted === undefined) {
+        return base.writeFileAtomic(path, bytes, options).catch(undeclared(path, prefixes));
+      }
+      const { mode } = vetted;
+      const staged = await deps.stage(bytes);
+      try {
+        await mustSucceed([
+          INSTALL,
+          "-S",
+          "-m",
+          mode,
+          ...options.uid === undefined ? [] : ["-o", String(options.uid)],
+          ...options.gid === undefined ? [] : ["-g", String(options.gid)],
+          staged.path,
+          path
+        ], staged.path);
+      } finally {
+        await staged.dispose();
+      }
+    }
+  };
+};
+var sudoRunner = (options) => {
+  const base = localRunner(options);
+  return makeSudoRunner(options.prefixes, {
+    base,
+    groups: () => operatorGroups(base),
+    log: options.log ?? ((line) => {
+      process.stderr.write(`${line}
+`);
+    }),
+    stage: stageFile
+  });
+};
 export {
   HostFile,
   HostFileProvider,
@@ -958,12 +1549,14 @@ export {
   LaunchdJob,
   LaunchdJobProvider,
   PlistError,
+  SudoRefusedError,
   canActAsRoot,
   hostRunnerLayer,
   launchdProviders,
   localRunner,
-  renderPlist
+  renderPlist,
+  sudoRunner
 };
 
-//# debugId=86750D103F13F7F764756E2164756E21
+//# debugId=59F08ED5EC139A6064756E2164756E21
 //# sourceMappingURL=index.js.map