@homeflare/alchemy 0.4.1 → 0.6.0

package/dist/openbao/ssh-role-form.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ssh-role-form.d.ts","sourceRoot":"","sources":["../../src/openbao/ssh-role-form.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,eAAe;IAC9B,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,0FAA0F;IAC1F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,yEAAyE;IACzE,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,sEAAsE;IACtE,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,qFAAqF;IACrF,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,4EAA4E;IAC5E,iBAAiB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACrD,oFAAoF;IACpF,sBAAsB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,0FAA0F;IAC1F,sBAAsB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1D,gFAAgF;IAChF,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAC;IACZ,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,eAAe,CAAC,CAAC;AAEvD,sFAAsF;AACtF,MAAM,WAAW,oBAAqB,SAAQ,IAAI,CAAC,cAAc,EAAE,QAAQ,GAAG,KAAK,CAAC;IAClF;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,wFAAwF;IACxF,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,8EAA8E;AAC9E,eAAO,MAAM,OAAO,UAAW,MAAM,GAAG,SAAS,WAAyC,CAAC;AAE3F,eAAO,MAAM,QAAQ,UAAW,MAAM,GAAG,SAAS,QAAQ,MAAM,WAC7B,CAAC;AAMpC;;;;GAIG;AACH,eAAO,MAAM,OAAO,UAAW,OAAO,KAAG,SAAS,MAAM,EAOvD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,MAAM,UAAW,OAAO,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAM5D,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,OAAO,UAAW,eAAe,KAAG,cAiB/C,CAAC;AAEH,eAAO,MAAM,YAAY,SACjB,cAAc,QACd,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,oBAqBF,CAAC;AAgBF;;;;;GAKG;AACH,eAAO,MAAM,SAAS,SAAU,cAAc,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAgBpE,CAAC;AAoBH;;;;;GAKG;AACH,eAAO,MAAM,YAAY,SAAU,cAAc,KAAG,SAAS,MAAM,EACuB,CAAC;AAE3F;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,eAAgB,oBAAoB,QAAQ,cAAc,YAe9B,CAAC"}
+{"version":3,"file":"ssh-role-form.d.ts","sourceRoot":"","sources":["../../src/openbao/ssh-role-form.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,UAAU,IAAI,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAExD,MAAM,WAAW,eAAe;IAC9B,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,0FAA0F;IAC1F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,yEAAyE;IACzE,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,sEAAsE;IACtE,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,qFAAqF;IACrF,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,4EAA4E;IAC5E,iBAAiB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACrD,oFAAoF;IACpF,sBAAsB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,0FAA0F;IAC1F,sBAAsB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1D,gFAAgF;IAChF,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAC;IACZ,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,eAAe,CAAC,CAAC;AAEvD,sFAAsF;AACtF,MAAM,WAAW,oBAAqB,SAAQ,IAAI,CAAC,cAAc,EAAE,QAAQ,GAAG,KAAK,CAAC;IAClF;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,wFAAwF;IACxF,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,OAAO,EAAE,OAAO,EAAE,CAAC;AAEnB,eAAO,MAAM,QAAQ,UAAW,MAAM,GAAG,SAAS,QAAQ,MAAM,WAC7B,CAAC;AAMpC;;;;GAIG;AACH,eAAO,MAAM,OAAO,UAAW,OAAO,KAAG,SAAS,MAAM,EAOvD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,MAAM,UAAW,OAAO,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAM5D,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,OAAO,UAAW,eAAe,KAAG,cAiB/C,CAAC;AAEH,eAAO,MAAM,YAAY,SACjB,cAAc,QACd,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,oBAqBF,CAAC;AAiBF;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,SAAU,cAAc,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAgBrE,CAAC;AAoBH;;;;;GAKG;AACH,eAAO,MAAM,YAAY,SAAU,cAAc,KAAG,SAAS,MAAM,EACuB,CAAC;AAE3F;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,eAAgB,oBAAoB,QAAQ,cAAc,YAe9B,CAAC"}

package/dist/openbao/ssh-role.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ssh-role.d.ts","sourceRoot":"","sources":["../../src/openbao/ssh-role.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAE7C,OAAO,KAAK,KAAK,UAAU,MAAM,iCAAiC,CAAC;AAEnE,OAAO,EACL,KAAK,oBAAoB,EAEzB,KAAK,eAAe,EAQrB,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,CAAC;AAEtD,MAAM,WAAW,UAAW,SAAQ,QAAQ,CAC1C,aAAa,EACb,eAAe,EACf,oBAAoB,EACpB,KAAK,EACL,UAAU,CAAC,UAAU,CACtB;CAAG;AAEJ,eAAO,MAAM,UAAU,6CAErB,CAAC;AAyDH,eAAO,MAAM,kBAAkB,iGAsH5B,CAAC"}
+{"version":3,"file":"ssh-role.d.ts","sourceRoot":"","sources":["../../src/openbao/ssh-role.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAE7C,OAAO,KAAK,KAAK,UAAU,MAAM,iCAAiC,CAAC;AAEnE,OAAO,EACL,KAAK,oBAAoB,EAEzB,KAAK,eAAe,EAQrB,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,CAAC;AAEtD,MAAM,WAAW,UAAW,SAAQ,QAAQ,CAC1C,aAAa,EACb,eAAe,EACf,oBAAoB,EACpB,KAAK,EACL,UAAU,CAAC,UAAU,CACtB;CAAG;AAEJ,eAAO,MAAM,UAAU,6CAErB,CAAC;AAyDH,eAAO,MAAM,kBAAkB,iGAqH5B,CAAC"}

package/docs/launchd.md

@@ -0,0 +1,167 @@
+# launchd — `@homeflare/alchemy/launchd`
+
+Declare a Mac host with Alchemy: its launchd jobs (`LaunchdJob`) and the config files they read
+(`HostFile`). launchd has no SDK, so the provider renders the plist itself and drives
+`launchctl`. Every file read, file write and `launchctl` call goes through one injectable
+`HostRunner`.
+
+```ts
+import * as Effect from 'effect/Effect';
+import { HostFile, LaunchdJob, launchdProviders } from '@homeflare/alchemy/launchd';
+
+export const exporter = Effect.gen(function* () {
+  const config = yield* HostFile('exporter-config', {
+    path: '/usr/local/etc/example-exporter.yml',
+    content: 'listen: 127.0.0.1:9100\n',
+    mode: 0o644,
+    owner: 'root',
+    group: 'wheel',
+  });
+  yield* LaunchdJob('exporter', {
+    label: 'com.example.exporter',
+    domain: 'system', // or 'gui/<uid>' for a LaunchAgent
+    // ★ config.path, not the literal: the Output orders the job after its file is written.
+    programArguments: ['/usr/local/bin/example-exporter', '--config', config.path],
+    environment: { TZ: 'UTC' }, // ⛔ non-secret values only
+    runAtLoad: true,
+    keepAlive: { successfulExit: false },
+    throttleInterval: 30,
+    standardOutPath: '/var/log/example-exporter.log',
+    standardErrorPath: '/var/log/example-exporter.log',
+  });
+});
+// Provide launchdProviders() alongside the stack's other provider layers.
+```
+
+## LaunchdJob
+
+| prop                          | plist key                        | notes                                                  |
+| ----------------------------- | -------------------------------- | ------------------------------------------------------ |
+| `label`                       | `Label`                          | also the file name; `[A-Za-z0-9._-]`, no `/`           |
+| `domain`                      | —                                | `system` (LaunchDaemons) or `gui/<uid>` (LaunchAgents) |
+| `programArguments`            | `ProgramArguments`               | first element must be an absolute path                 |
+| `environment`                 | `EnvironmentVariables`           | ⛔ non-secret only (see below)                         |
+| `runAtLoad`                   | `RunAtLoad`                      |                                                        |
+| `keepAlive`                   | `KeepAlive`                      | `true`/`false` or `{ successfulExit, crashed }`        |
+| `startInterval`               | `StartInterval`                  | seconds, > 0                                           |
+| `startCalendarInterval`       | `StartCalendarInterval`          | one entry or a list; fields are range-checked          |
+| `throttleInterval`            | `ThrottleInterval`               | seconds, ≥ 0                                           |
+| `standardOutPath` / `…Error…` | `StandardOutPath` / `…ErrorPath` | absolute                                               |
+| `workingDirectory`            | `WorkingDirectory`               | absolute                                               |
+| `userName` / `groupName`      | `UserName` / `GroupName`         | system domain only — launchd ignores them for agents   |
+| `extraKeys`                   | anything else, verbatim          | may not repeat a key a typed prop owns                 |
+
+The plist path is derived, never declared: `/Library/LaunchDaemons/<label>.plist` for `system`,
+`<home of uid>/Library/LaunchAgents/<label>.plist` for `gui/<uid>`.
+
+| step    | what happens                                                                                        |
+| ------- | --------------------------------------------------------------------------------------------------- |
+| create  | write the plist atomically (system: `root:wheel 0644`), then `launchctl bootstrap`                  |
+| update  | write, `bootout` the running job (and wait until launchd lets go), `bootstrap` — **a restart**      |
+| read    | `launchctl print` (loaded? state, pid, last exit) plus the SHA-256 of the plist on disk             |
+| diff    | the rendered plist's SHA-256 against the stored digest **and** the on-disk one, plus "is it loaded" |
+| replace | only when `label` or `domain` changes — **delete first**, so two copies never run at once           |
+| delete  | `bootout` if loaded, remove the plist; idempotent                                                   |
+
+- A converged job is not restarted: a retried deploy that finds the right plist loaded does nothing.
+- ⛔ **A rename is checked at plan time.** Alchemy deletes the old job before it creates the new
+  one, so everything the new one would be refused for (an invalid or reserved label, a domain you
+  may not write, a disabled label, a label another job already holds) fails the **plan**, with the
+  old job still running. A rename is seen even while other props are unresolved Outputs.
+- ⚠️ A failed `bootstrap` leaves the job **down**. On an update the new plist stays on disk, the
+  state keeps the old digest, and the next deploy retries. On a first create the plist is removed
+  again, so the next plan does not find its own file and call it someone else's.
+  There is no rollback to an older plist.
+- ⛔ A label disabled with `launchctl disable` is refused, not re-enabled: that was someone's
+  decision. The error names the `launchctl enable` command to run if it is stale.
+- ⚠️ A `gui/<uid>` job needs that user logged in: without a login session the domain does not
+  exist (`launchctl print` exits 112, "Could not find domain"; measured). Deploying refuses before
+  it writes anything. Deleting still removes the plist, which stops launchd loading it at login.
+- ⚠️ The digest covers the rendered bytes, so a kit upgrade that changes the renderer's output
+  restarts every declared job on the next deploy. Such a release says so in its changelog.
+
+## HostFile
+
+`path` (absolute, normalised), `content` (UTF-8 text), `mode` (default `0o644`), `owner` and
+`group` (names or ids). Written as a temp file in the same directory — mode and owner set before
+it becomes visible — then renamed over the path. Read back after every write. Diffed by SHA-256,
+mode and owner. A new `path` is a create-before-delete replace. Delete removes the file.
+
+- ⛔ A different file already at a new `path` is refused, not overwritten: the adoption probe
+  never looks at a replace's new path, so a typo there would otherwise overwrite a system file.
+
+- ⛔ A symlink or directory at the path is refused, never replaced: rename over a symlink replaces
+  the link, which takes the path from whatever tool owns it (nix-darwin's `/etc` entries point
+  into `/nix/store`).
+- ⚠️ The parent directory must exist. Creating it would invent an owner and mode nobody declared.
+
+## ⛔ No secrets in props
+
+Alchemy stores props and attributes **unencrypted** in its state store. A job's `environment`,
+`programArguments` and `extraKeys`, and a file's `content`, land there, in every plan diff, and on
+disk.
+
+**Keep secret files rendered by a secret renderer** — `openbao-agent` templates on a HomeFlare
+host — and declare only the path: `FOO_TOKEN_FILE=/path`, `--token-file /path`. A tripwire refuses
+the obvious mistakes (a `*_TOKEN`/`*_PASSWORD`-style variable, `--token=…`, a PEM private key); it
+is not a scanner, and passing it does not make a value safe to declare.
+
+## ⛔ No silent sudo
+
+The `system` domain, and another user's `gui/<uid>`, need root. The provider refuses up front
+unless the runner is root (`effectiveUid() === 0`) or was deliberately built with
+`privileged: true`. `localRunner()` — the default — is never privileged and never calls `sudo`, so:
+
+- **system daemons:** start the whole deploy as root; or pass `launchdProviders(yourRunner)` where
+  `yourRunner` is a `HostRunner` you wrote that already holds root (a root helper, say).
+- **your own agents** (`gui/<your uid>`): no root needed.
+
+Reading (`launchctl print`, `print-disabled`) needs no root. ⚠️ A `HostFile` whose mode hides it
+from the planning user (a root-owned `0600`, say) fails the plan with `EACCES`: plan as the user
+you deploy as.
+
+## Adoption: nothing is taken over silently
+
+`read` with no prior state reports anything it finds — a loaded label, a plist, a file — as
+`Unowned`, so Alchemy refuses to take it over without `--adopt`.
+
+Labels under `org.nixos.`, `com.apple.` and `homebrew.mxcl.` are **refused outright**. nix-darwin
+rewrites its plists on every activation and unloads any it no longer lists, macOS owns
+`com.apple.*`, and `brew services` owns `homebrew.mxcl.*`. Adopting one would give a file two
+owners. Move the job instead.
+
+## Cutover from nix-darwin
+
+Nix-managed `org.nixos.*` jobs are **not adopted**. The host stack declares a **new** label, and the
+Nix job is booted out first. Per job:
+
+1. **Declare** the replacement in the host stack under a new label (`com.example.<job>`), with its
+   config as `HostFile`s. ⚠️ Nothing it references may live in `/nix/store` — the next garbage
+   collection deletes it. Plan it: expect creates only.
+2. **Remove the job from the nix-darwin config and activate.** Activation unloads and deletes every
+   daemon it no longer lists — checked 2026-09-21 in a nix-darwin activation script: it prints
+   `removing service <label>`, runs `launchctl unload`, then removes the plist. Confirm with
+   `launchctl print system/org.nixos.<job>` → exit 113 ("Could not find service").
+3. **Deploy** the host stack. The new label bootstraps.
+4. **Verify** `launchctl print system/com.example.<job>` shows `state = running`, then check the
+   service itself (port, metrics, logs).
+
+- ★ **Why this order.** Both jobs usually bind the same port and write the same files; the old one
+  must be gone before the new one starts. Downtime is one deploy.
+- ⚠️ **`sudo launchctl bootout system/org.nixos.<job>` is not a cutover.** The plist stays in
+  `/Library/LaunchDaemons`, so launchd loads it again at the next boot; and activation (checked in
+  the same script) copies back and `load -w`s any Nix plist that is missing or differs from the
+  store. Either way two copies end up fighting over the port.
+- ⚠️ **Check the host's own activation for labels it removes.** An activation script can boot out,
+  `disable` and delete jobs by name on every run; a new label that collides with one is disabled
+  under you. `grep -n 'bootout\|disable' /run/current-system/activate` before choosing labels.
+- **Rolling back** is the same three steps reversed: destroy (or remove) the resource, restore the
+  job in the Nix config, activate.
+
+## The runner
+
+`HostRunner` (see `src/launchd/runner.ts`) is `exec(argv)` (never through a shell), `readFile`,
+`stat` (lstat), `writeFileAtomic`, `removeFile`, `lookupUser`, `lookupGroup`, `sleep`, plus
+`privileged` and `effectiveUid()`. `localRunner()` implements it with `node:fs` and
+`node:child_process`; tests use an in-memory fake, so nothing in the test suite runs `launchctl` or
+writes outside a temp directory.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.4.1",
-  "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo and Talos.",
+  "version": "0.6.0",
+  "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos and launchd.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
   "license": "MIT",
@@ -13,6 +13,7 @@
   },
   "files": [
     "dist",
+    "docs",
     "src",
     "README.md",
     "LICENSE"
@@ -44,6 +45,10 @@
       "types": "./dist/proxmox/index.d.ts",
       "default": "./dist/proxmox/index.js"
     },
+    "./launchd": {
+      "types": "./dist/launchd/index.d.ts",
+      "default": "./dist/launchd/index.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {

package/src/index.ts

@@ -9,6 +9,7 @@
  *     import { BaoMount } from '@homeflare/alchemy/openbao';
  *     import { TalosCluster } from '@homeflare/alchemy/talos';
  *     import { ProxmoxAcl } from '@homeflare/alchemy/proxmox';
+ *     import { LaunchdJob } from '@homeflare/alchemy/launchd';
  *
  * ★ WHY THESE EXIST AT ALL. When Alchemy has no resource for something, the alternative
  *   is a runbook step a human runs once — and a plan can never show a missing runbook

package/src/launchd/fake-runner.ts

@@ -0,0 +1,176 @@
+/**
+ * An in-memory host for the tests beside it: a filesystem in a Map and a scripted launchd.
+ *
+ * ⛔ TEST-ONLY. No provider imports this file, it is not on the barrel, and it never touches the
+ *   real filesystem or runs a real program — which is the only way the lifecycle tests can prove
+ *   "bootout before bootstrap" without writing /Library or loading a job.
+ * ★ IT MODELS THE BEHAVIOURS THE PROVIDER DEPENDS ON, as launchctl.ts documents them: `print` of an
+ *   unknown target exits 113; bootstrap of a loaded or disabled label fails; bootout of an absent
+ *   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.
+ */
+import { LAUNCHCTL, NOT_FOUND, NO_DOMAIN } from './launchctl.ts';
+import type { ExecResult, FileStat, HostRunner, HostUser, WriteOptions } from './runner.ts';
+
+type Entry = { bytes: Uint8Array; mode: number; uid: number; gid: number; kind: FileStat['kind'] };
+
+export type FakeOptions = {
+  euid?: number;
+  privileged?: boolean;
+  /** Directories that exist, and their owner uid. */
+  dirs?: Record<string, number>;
+  users?: Record<string, HostUser>;
+  groups?: Record<string, number>;
+};
+
+const ok = (stdout = ''): ExecResult => ({ exitCode: 0, stderr: '', stdout });
+const fail = (exitCode: number, stderr: string): ExecResult => ({ exitCode, stderr, stdout: '' });
+const errno = (code: string, path: string) =>
+  Object.assign(new Error(`${code}: ${path}`), { code });
+const parent = (path: string) => path.slice(0, path.lastIndexOf('/')) || '/';
+
+/** The shape `launchctl print` produced on macOS 27.2 (see launchctl.ts), trimmed. */
+const printBlock = (target: string, pid: number | undefined, lastExit: string) =>
+  [
+    `${target} = {`,
+    '\tactive count = 1',
+    `\tstate = ${pid === undefined ? 'not running' : 'running'}`,
+    '\targuments = {',
+    '\t\t/bin/sh',
+    '}',
+    '\t}',
+    '\tresource coalition = {',
+    '\t\tstate = active',
+    '\t}',
+    ...(pid === undefined ? [] : [`\tpid = ${String(pid)}`]),
+    `\tlast exit code = ${lastExit}`,
+    '}',
+  ].join('\n');
+
+export const fakeRunner = (options: FakeOptions = {}) => {
+  const euid = options.euid ?? 501;
+  const privileged = options.privileged ?? false;
+  const root = privileged || euid === 0;
+  const dirs = new Map(Object.entries(options.dirs ?? {}));
+  const files = new Map<string, Entry>();
+  const calls: string[][] = [];
+  /** target → pid (undefined = loaded, not running). */
+  const loaded = new Map<string, number | undefined>();
+  const disabled = new Set<string>();
+  const state = {
+    lingerPrints: 0,
+    nextPid: 4000,
+    bootstrapFailure: undefined as ExecResult | undefined,
+    /** Returned by bootout in place of success. The job still goes, unless `bootoutKeepsJob`. */
+    bootoutFailure: undefined as ExecResult | undefined,
+    bootoutKeepsJob: false,
+    /** gui uids with no login session: every launchctl call into `gui/<uid>` exits 112. */
+    loggedOut: new Set<number>(),
+  };
+  /** Booted-out targets launchd has not let go of yet → prints left before they vanish. */
+  const lingering = new Map<string, number>();
+
+  const labelIn = (path: string) =>
+    /<key>Label<\/key>\s*<string>([^<]*)<\/string>/.exec(
+      new TextDecoder().decode(files.get(path)?.bytes),
+    )?.[1];
+
+  const launchctl = (args: readonly string[]): ExecResult => {
+    const [sub, first, second] = args;
+    const gui = /^gui\/(\d+)(?:\/|$)/.exec(first ?? '')?.[1];
+    if (gui !== undefined && state.loggedOut.has(Number(gui))) {
+      // The measured shape (launchctl.ts): 112, "Bad request." then the domain line.
+      return fail(NO_DOMAIN, `Bad request.\nCould not find domain for user gui: ${gui}`);
+    }
+    if (sub === 'print' && first !== undefined) {
+      const left = lingering.get(first);
+      if (left !== undefined) {
+        if (left <= 0) {
+          lingering.delete(first);
+          loaded.delete(first);
+        } else lingering.set(first, left - 1);
+      }
+      if (!loaded.has(first)) return fail(NOT_FOUND, `Could not find service "${first}"`);
+      return ok(printBlock(first, loaded.get(first), '(never exited)'));
+    }
+    if (sub === 'print-disabled' && first !== undefined) {
+      const lines = [...disabled]
+        .filter((target) => target.startsWith(`${first}/`))
+        .map((target) => `\t\t"${target.slice(first.length + 1)}" => disabled`);
+      return ok(['\tdisabled services = {', ...lines, '\t}'].join('\n'));
+    }
+    if (sub === 'bootstrap' && first !== undefined && second !== undefined) {
+      if (state.bootstrapFailure !== undefined) return state.bootstrapFailure;
+      const label = labelIn(second);
+      if (label === undefined) return fail(5, 'Bootstrap failed: 5: Input/output error');
+      const target = `${first}/${label}`;
+      if (loaded.has(target) || disabled.has(target))
+        return fail(5, 'Bootstrap failed: 5: Input/output error');
+      state.nextPid += 1;
+      loaded.set(target, state.nextPid);
+      return ok();
+    }
+    if (sub === 'bootout' && first !== undefined) {
+      if (!loaded.has(first) || lingering.has(first))
+        return fail(3, 'Boot-out failed: 3: No such process');
+      if (state.bootoutKeepsJob) return state.bootoutFailure ?? fail(5, 'Boot-out failed: 5');
+      // ⚠️ Model launchd letting go late: the job stays visible for `lingerPrints` more prints.
+      if (state.lingerPrints === 0) loaded.delete(first);
+      else lingering.set(first, state.lingerPrints);
+      return state.bootoutFailure ?? ok();
+    }
+    return fail(64, `fake launchctl: unsupported ${args.join(' ')}`);
+  };
+
+  const runner: HostRunner = {
+    effectiveUid: () => euid,
+    exec: async (argv) => {
+      calls.push([...argv]);
+      if (argv[0] === LAUNCHCTL) return launchctl(argv.slice(1));
+      return fail(127, `fake: no program ${String(argv[0])}`);
+    },
+    lookupGroup: async (nameOrId) => options.groups?.[nameOrId],
+    lookupUser: async (nameOrId) =>
+      options.users?.[nameOrId] ??
+      Object.values(options.users ?? {}).find((user) => String(user.uid) === nameOrId),
+    privileged,
+    readFile: async (path) => files.get(path)?.bytes,
+    removeFile: async (path) => {
+      if (files.has(path) && (dirs.get(parent(path)) ?? 0) !== euid && !root)
+        throw errno('EACCES', path);
+      files.delete(path);
+    },
+    // ★ No real waiting: a lingering job drains one `print` per poll instead.
+    sleep: async () => undefined,
+    stat: async (path) => {
+      const entry = files.get(path);
+      if (entry !== undefined)
+        return {
+          gid: entry.gid,
+          kind: entry.kind,
+          mode: entry.mode,
+          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;
+    },
+    writeFileAtomic: async (path: string, bytes: Uint8Array, write: WriteOptions) => {
+      calls.push(['write', path]);
+      const owner = dirs.get(parent(path));
+      if (owner === undefined) throw errno('ENOENT', parent(path));
+      if (owner !== euid && !root) throw errno('EACCES', path);
+      if (write.uid !== undefined && write.uid !== euid && !root) throw errno('EPERM', path);
+      files.set(path, {
+        bytes,
+        gid: write.gid ?? 20,
+        kind: 'file',
+        mode: write.mode,
+        uid: write.uid ?? euid,
+      });
+    },
+  };
+  return { calls, disabled, dirs, files, loaded, runner, state };
+};

package/src/launchd/host-effect.ts

@@ -0,0 +1,28 @@
+/**
+ * The one place a HostRunner's promises become Effects — plus the one probe of an unresolved
+ * `news` both providers' diffs share.
+ *
+ * ★ 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, …))`.
+ * ⚠️ A thrown Error stays that Error — its message is the refusal a deploy prints. Anything else
+ *   thrown is wrapped, so the failure channel is always an Error with a readable message.
+ */
+import * as Effect from 'effect/Effect';
+
+export const lift = <A>(step: () => Promise<A>): Effect.Effect<A, Error> =>
+  Effect.tryPromise({
+    catch: (cause) => (cause instanceof Error ? cause : new Error(String(cause))),
+    try: step,
+  });
+
+/**
+ * A string prop of a diff's `news`, when that one prop is already resolved; `undefined` while it
+ * is still an Output (a function-typed proxy), an Effect or a Config.
+ * ★ For the identity props a diff must see even when the rest of `news` is unresolved — a plain
+ *   string is resolved by definition, so `typeof` is the whole test.
+ */
+export const resolvedString = (news: unknown, key: string): string | undefined => {
+  if (typeof news !== 'object' || news === null) return undefined;
+  const value = (news as Record<string, unknown>)[key];
+  return typeof value === 'string' ? value : undefined;
+};

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