@homeflare/alchemy 0.14.0 → 0.19.0

package/docs/provision-baseline.md

@@ -4,13 +4,14 @@ Every `@homeflare/alchemy/proxmox` resource runs as a short-lived PVE token that
 a **provision user**. That user, and the access it holds, is the baseline a cluster needs before a
 stack can manage anything on it. This subpath ships it as one description with two readers:
 
-| export                      | what it is                                                                                  |
-| --------------------------- | ------------------------------------------------------------------------------------------- |
-| `PROVISION_PRIVILEGES`      | the provision role's privileges: 27, sorted, the exact set                                  |
-| `PROVISION_DEFAULTS`        | the generic names in the last table, each overridable                                       |
-| `provisionBaseline(names)`  | the resolved baseline both readers use; refuses names that are not PVE-shaped               |
-| `declareProvisionBaseline`  | the baseline as `Proxmox.Role`, `Proxmox.Group`, `Proxmox.User` and `Proxmox.Acl` resources |
-| `provisionBootstrap(names)` | the one-time root commands for a new cluster or node, as a `sh` script                      |
+| export                      | what it is                                                                                          |
+| --------------------------- | --------------------------------------------------------------------------------------------------- |
+| `PROVISION_PRIVILEGES`      | the provision role's privileges: 27, sorted, the exact set                                          |
+| `PROVISION_DEFAULTS`        | the generic names in the last table, each overridable                                               |
+| `ProvisionNames`            | those names, plus `groupComment` / `provisionComment` / `readComment`, each defaulting to `comment` |
+| `provisionBaseline(names)`  | the resolved baseline both readers use; refuses names that are not PVE-shaped                       |
+| `declareProvisionBaseline`  | the baseline as `Proxmox.Role`, `Proxmox.Group`, `Proxmox.User` and `Proxmox.Acl` resources         |
+| `provisionBootstrap(names)` | the one-time root commands for a new cluster or node, as a `sh` script                              |
 
 ## The chicken and the egg
 
@@ -52,6 +53,30 @@ So root makes it once, and the stack takes it over from there:
    clean adoption and the deploy writes nothing. From then on, a hand edit (a privilege added in
    the UI, a user dropped from the group) shows up as a diff on the next plan.
 
+## A cluster that already exists
+
+⚠️ **The common case is not a blank cluster.** One that already has a mint group and a
+read user — with their own live comments, which another stack may already declare at
+those values — must not have them rewritten by a bootstrap that only came to add a
+provision lane. A comment per object says that, and each one defaults to `comment`:
+
+```ts
+const names = {
+  role: 'LXCProvisioner',
+  groupComment: '', // live: no comment at all
+  readComment: 'mint target: read (ops)', // live: its own wording
+  provisionComment: 'mint target: provision (ops)', // the one new object
+};
+```
+
+The script then prints `group hf-mint: ok` and `user hf-read@pve: ok` and writes only
+the role, the new user and its grant. ⛔ With one shared comment it would modify all
+three, and the next deploy of the stack that declares the other two would write them
+back — a loop that looks like drift and is not.
+
+★ `readComment` goes with its lane: a `null` `readUser` drops the user, so the field is
+neither used nor checked.
+
 ## Every cluster, every node
 
 - **A new cluster:** run the bootstrap on one node, then deploy.
@@ -71,6 +96,8 @@ declareProvisionBaseline('pve', target, names); // the resources
 ```
 
 - `readUser: null` gives a baseline with no read lane.
+- `comment` is every object's comment; `groupComment`, `provisionComment` and
+  `readComment` override it one object at a time.
 - `readRole` must already exist (`PVEAuditor` is built in). The script stops before any write if
   it does not.
 - A name that is not PVE-shaped, or that would need quoting in a shell, is refused by both

package/docs/proxmox-lxc.md

@@ -143,6 +143,46 @@ guest that needs `/dev/net/tun` (a Mesh door) or `/dev/dri` is created in two st
 - **Pool membership, HA, firewall rules, snapshots, replication** are not declared here. Use their
   own resources, or manage them by hand.
 
+### ⛔ The guest's INSIDE is not reachable, and no kit Resource can change that
+
+This resource declares a guest's PVE-level config: the keys in
+`/nodes/{node}/lxc/{vmid}/config`. It cannot install a package, write a file into the guest, or
+define a service — and **neither can anything else built on PVE's API**, because PVE does not
+expose it for containers:
+
+| Reach inside  | QEMU VM                               | LXC container |
+| ------------- | ------------------------------------- | ------------- |
+| Run a command | `POST …/qemu/{vmid}/agent/exec`       | —             |
+| Write a file  | `POST …/qemu/{vmid}/agent/file-write` | —             |
+| Read a file   | `GET …/qemu/{vmid}/agent/file-read`   | —             |
+| cloud-init    | `…/qemu/{vmid}/cloudinit`             | —             |
+
+Measured across the whole `/nodes/{node}/lxc/{vmid}/…` endpoint set in
+`src/proxmox/generated/pve.ts`, and pinned by `src/proxmox/lxc-interior.test.ts` so that it fails
+the day PVE adds one. The only reach inside is `termproxy` / `vncwebsocket`, an interactive
+console for a person — not something a resource can diff.
+
+⚠️ **Sibling families are not at parity.** QEMU and LXC sit under the same `/nodes/{node}/…` tree
+and have completely different reach. Do not infer one from the other, here or anywhere else.
+
+So a generic, vendor-API-based Resource for a container's interior **cannot be written**: there is
+nothing to wrap. What is left, in the order that keeps a change declarative:
+
+1. **Bake it into the template.** Publish a rootfs tarball to `vztmpl` and name it as
+   `ostemplate`. ⚠️ `ostemplate` is create-only and never read back, so the interior gets no drift
+   detection, and changing it REPLACES the guest. Right for something stateless and immutable; a
+   decision for anything else.
+2. **A first-boot artifact** the image already carries, which configures itself from what it can
+   see locally.
+3. **A recorded one-time human step**, named as undeclared.
+
+⛔ **An exec-over-SSH resource is not option zero.** It is reachable, but not through the vendor,
+so it needs a credential and a network path _to the guest_ — and if the guest is what provides
+credentials, naming or network reach to others, that inverts the bootstrap: the new system's first
+boot then depends on its own output, and it fails when the dependency is down. The
+`@homeflare/alchemy/launchd` `HostRunner` seam is where such a runner would plug in, and the kit
+ships only `localRunner()` and `sudoRunner()` on purpose.
+
 ## Adopting
 
 ⛔ **No live guest is adopted without `adopt(true)` or `--adopt`, and an adoption never changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.14.0",
+  "version": "0.19.0",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
@@ -56,6 +56,14 @@
       "types": "./dist/launchd/index.d.ts",
       "default": "./dist/launchd/index.js"
     },
+    "./netbox": {
+      "types": "./dist/netbox/index.d.ts",
+      "default": "./dist/netbox/index.js"
+    },
+    "./linux": {
+      "types": "./dist/linux/index.d.ts",
+      "default": "./dist/linux/index.js"
+    },
     "./caddy": {
       "types": "./dist/caddy/index.d.ts",
       "default": "./dist/caddy/index.js"

package/src/linux/directory-lifecycle.ts

@@ -0,0 +1,220 @@
+/**
+ * HostDirectory's props, validation and lifecycle over a HostRunner.
+ *
+ * ★ WHY IT EXISTS AT ALL. `Host.File` and `Remote.File` both refuse to create a parent directory,
+ *   on purpose — creating one would invent an owner and a mode nobody declared. The consequence is
+ *   that a first deploy into a new tree fails on its first file. This resource is the declaration
+ *   that was missing, not a convenience flag on the file.
+ * ⛔ ONE DIRECTORY, NEVER A CHAIN. A missing parent is a refusal that names it, so a tree is a
+ *   chain of declarations whose modes and owners are all visible in the plan. `mkdir -p` would
+ *   create the intermediate levels at whatever umask the deploy happened to run with.
+ * ⛔ DELETE IS `rmdir`, NEVER RECURSIVE. A directory that still holds files is a refusal: removing
+ *   a declaration must not be able to remove data the declaration never mentioned.
+ */
+import type { Diff } from 'alchemy/Diff';
+import { pathProblems } from '../launchd/host-file-form.ts';
+import { type HostRunner, canActAsRoot } from '../launchd/runner.ts';
+
+export interface HostDirectoryProps {
+  /** Absolute path. ⚠️ Its parent must already exist — declare it as another HostDirectory. */
+  path: string;
+  /** Permission bits. @default 0o755 */
+  mode?: number;
+  /** User name or numeric uid. Omitted: whoever the runner writes as. */
+  owner?: string | number;
+  /** Group name or numeric gid. Omitted: the parent's default group. */
+  group?: string | number;
+}
+
+export interface HostDirectoryAttributes {
+  path: string;
+  mode: number;
+  uid: number;
+  gid: number;
+}
+
+export const DEFAULT_DIR_MODE = 0o755;
+
+export const refuse = (path: string, message: string): Error =>
+  new Error(`Host.Directory ${path}: ${message}`);
+
+const idProblems = (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 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 directoryProblems = (props: HostDirectoryProps): string[] => {
+  const found = pathProblems(props.path);
+  const mode = props.mode ?? DEFAULT_DIR_MODE;
+  if (!Number.isSafeInteger(mode) || mode < 0 || mode > 0o7777) found.push('mode must be 0–0o7777');
+  found.push(...idProblems('owner', props.owner), ...idProblems('group', props.group));
+  return found;
+};
+
+const numericId = (value: string | number): number | undefined =>
+  typeof value === 'number' ? value : /^\d+$/.test(value) ? Number(value) : undefined;
+
+type Desired = { readonly mode: number; readonly uid?: number; readonly gid?: number };
+
+const desired = async (runner: HostRunner, props: HostDirectoryProps): Promise<Desired> => {
+  const found = directoryProblems(props);
+  if (found.length > 0) throw refuse(props.path, found.join('; '));
+  let uid: number | undefined;
+  let gid: number | undefined;
+  if (props.owner !== undefined) {
+    uid = numericId(props.owner) ?? (await runner.lookupUser(String(props.owner)))?.uid;
+    if (uid === undefined) throw refuse(props.path, `no user ${String(props.owner)} on this host`);
+  }
+  if (props.group !== undefined) {
+    gid = numericId(props.group) ?? (await runner.lookupGroup(String(props.group)));
+    if (gid === undefined) throw refuse(props.path, `no group ${String(props.group)} on this host`);
+  }
+  return {
+    mode: props.mode ?? DEFAULT_DIR_MODE,
+    ...(uid === undefined ? {} : { uid }),
+    ...(gid === undefined ? {} : { gid }),
+  };
+};
+
+export const readDirectory = async (
+  runner: HostRunner,
+  path: string,
+): Promise<HostDirectoryAttributes | undefined> => {
+  const stat = await runner.stat(path);
+  if (stat === undefined || stat.kind !== 'directory') return undefined;
+  return { gid: stat.gid, mode: stat.mode, path, uid: stat.uid };
+};
+
+const octal = (mode: number) => mode.toString(8).padStart(3, '0');
+
+/** One program, checked: anything but exit 0 is an Error naming the argv and the host's words. */
+const must = async (runner: HostRunner, path: string, argv: readonly string[]): Promise<void> => {
+  const result = await runner.exec(argv);
+  if (result.exitCode !== 0) {
+    throw refuse(
+      path,
+      `${argv.join(' ')} -> ${String(result.exitCode)}: ${result.stderr.trim().slice(0, 300)}`,
+    );
+  }
+};
+
+/**
+ * Create it when absent, then bring mode and ownership to the declaration and read back.
+ * ⚠️ `mkdir -m` sets the mode with chmod(2) after mkdir(2), so it is exact — plain `mkdir` would
+ *   mask the declared bits through the deploying shell's umask and the drift would return forever.
+ */
+export const reconcileDirectory = async (
+  runner: HostRunner,
+  props: HostDirectoryProps,
+  output?: HostDirectoryAttributes,
+  adopt = false,
+): Promise<HostDirectoryAttributes> => {
+  const want = await desired(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 through ` +
+        'a root destination or a privileged HostRunner. This provider never calls sudo itself.',
+    );
+  }
+  const stat = await runner.stat(props.path);
+  if (stat !== undefined && stat.kind !== 'directory') {
+    throw refuse(props.path, `is a ${stat.kind}, not a directory`);
+  }
+  /**
+   * ⛔ A DIRECTORY THIS RESOURCE DOES NOT OWN IS NEVER RE-MODED. Where the engine's probe never
+   *   looked — a replace's new path, a create whose props were still an Output — an existing
+   *   directory with a different mode or owner is someone else's. ★ Adoption takes it over.
+   */
+  if (output === undefined && stat !== undefined && !adopt) {
+    const drifted = stat.mode !== want.mode || (want.uid !== undefined && stat.uid !== want.uid);
+    if (drifted) {
+      throw refuse(
+        props.path,
+        'already exists with another mode or owner and is not this resource. Remove it, or ' +
+          'declare it as a new resource and deploy with --adopt.',
+      );
+    }
+  }
+  if (stat === undefined) {
+    const parent = props.path.slice(0, props.path.lastIndexOf('/')) || '/';
+    const above = await runner.stat(parent);
+    if (above === undefined || above.kind !== 'directory') {
+      throw refuse(props.path, `its parent ${parent} does not exist; declare that directory too`);
+    }
+    await must(runner, props.path, ['mkdir', '-m', octal(want.mode), '--', props.path]);
+  } else if (stat.mode !== want.mode) {
+    await must(runner, props.path, ['chmod', octal(want.mode), '--', props.path]);
+  }
+  /**
+   * ★ Only when it is actually wrong. A `chown` that changes nothing is still a write on the host
+   *   and a line in the deploy log, and "a converged resource is not touched" is the rule this
+   *   whole family is judged by.
+   */
+  const owner = ownerMatches(
+    { gid: stat?.gid ?? -1, mode: 0, path: props.path, uid: stat?.uid ?? -1 },
+    want,
+  )
+    ? undefined
+    : ownerArg(want);
+  if (owner !== undefined) await must(runner, props.path, ['chown', owner, '--', props.path]);
+  const after = await readDirectory(runner, props.path);
+  // ⚠️ READ BACK: a runner that ignored the mode shows up here, not as a forever-`update`.
+  if (after === undefined || after.mode !== want.mode || !ownerMatches(after, want)) {
+    throw refuse(props.path, 'the directory on the host does not match the declaration');
+  }
+  return after;
+};
+
+/** ⛔ Never `<uid>:` — GNU chown reads a trailing colon as that user's LOGIN group, undeclared. */
+const ownerArg = (want: Desired): string | undefined => {
+  if (want.uid === undefined) return want.gid === undefined ? undefined : `:${String(want.gid)}`;
+  return want.gid === undefined ? String(want.uid) : `${String(want.uid)}:${String(want.gid)}`;
+};
+
+const ownerMatches = (live: HostDirectoryAttributes, want: Desired): boolean =>
+  (want.uid === undefined || live.uid === want.uid) &&
+  (want.gid === undefined || live.gid === want.gid);
+
+/**
+ * ★ A plan that will write asks the runner first (`checkWrite`, when it has one) — a directory is
+ *   created and chmod'd through `exec`, but a runner that refuses to touch the path at all should
+ *   say so at plan time rather than mid-apply.
+ */
+export const diffDirectory = async (
+  runner: HostRunner,
+  news: HostDirectoryProps,
+  output: HostDirectoryAttributes,
+): Promise<Diff> => {
+  const want = await desired(runner, news);
+  if (news.path !== output.path) return { action: 'replace' };
+  const live = await readDirectory(runner, news.path);
+  // ⛔ BOTH: the live directory catches a hand chmod, the stored attributes catch a deploy that
+  //   died after the mkdir and before its commit.
+  const converged =
+    live !== undefined &&
+    live.mode === want.mode &&
+    ownerMatches(live, want) &&
+    output.mode === want.mode &&
+    ownerMatches(output, want);
+  if (converged) return { action: 'noop' };
+  await runner.checkWrite?.(news.path, want);
+  return { action: 'update' };
+};
+
+/** Remove it. ⛔ `rmdir`: a directory that still holds anything is a refusal, never a recursion. */
+export const deleteDirectory = async (
+  runner: HostRunner,
+  output: HostDirectoryAttributes,
+): Promise<void> => {
+  const stat = await runner.stat(output.path);
+  if (stat === undefined) return;
+  if (stat.kind !== 'directory')
+    throw refuse(output.path, `is now a ${stat.kind}; not removing it`);
+  await must(runner, output.path, ['rmdir', '--', output.path]);
+};

package/src/linux/directory.test.ts

@@ -0,0 +1,132 @@
+/**
+ * HostDirectory against the fake host: the resource that exists because every file resource refuses
+ * to create a parent.
+ */
+import { describe, expect, test } from 'bun:test';
+import {
+  deleteDirectory,
+  diffDirectory,
+  directoryProblems,
+  readDirectory,
+  reconcileDirectory,
+} from './directory-lifecycle.ts';
+import { fakeLinuxHost } from './fake-linux-host.ts';
+
+const host = () =>
+  fakeLinuxHost({
+    dirs: { '/opt/app': 0 },
+    groups: { app: 60 },
+    users: { app: { gid: 60, home: '/opt/app', uid: 900 } },
+  });
+
+describe('create', () => {
+  test('makes the directory with the declared mode and owner, then reads it back', async () => {
+    const fake = host();
+    const attrs = await reconcileDirectory(fake.runner, {
+      group: 'app',
+      mode: 0o750,
+      owner: 'app',
+      path: '/opt/app/etc',
+    });
+    expect(attrs).toEqual({ gid: 60, mode: 0o750, path: '/opt/app/etc', uid: 900 });
+    // ⚠️ `mkdir -m` carries the mode, so a umask never masks a declared bit.
+    expect(fake.calls.some((call) => call[0] === 'mkdir' && call.includes('750'))).toBe(true);
+  });
+
+  test('a missing parent is a refusal that names it, never an mkdir -p', async () => {
+    const fake = host();
+    await expect(reconcileDirectory(fake.runner, { path: '/opt/app/one/two' })).rejects.toThrow(
+      /its parent \/opt\/app\/one does not exist/,
+    );
+    expect(fake.calls.some((call) => call.includes('-p'))).toBe(false);
+  });
+
+  test('a path that is a file is refused rather than replaced', async () => {
+    const fake = host();
+    await fake.runner.writeFileAtomic('/opt/app/thing', new Uint8Array(), { mode: 0o644 });
+    await expect(reconcileDirectory(fake.runner, { path: '/opt/app/thing' })).rejects.toThrow(
+      /is a file, not a directory/,
+    );
+  });
+});
+
+describe('drift', () => {
+  test('a hand chmod is an update, and reconcile puts it back', async () => {
+    const fake = host();
+    const output = await reconcileDirectory(fake.runner, { mode: 0o750, path: '/opt/app/etc' });
+    expect(await diffDirectory(fake.runner, { mode: 0o750, path: '/opt/app/etc' }, output)).toEqual(
+      {
+        action: 'noop',
+      },
+    );
+    const live = fake.modes.get('/opt/app/etc');
+    if (live !== undefined) live.mode = 0o777;
+    expect(await diffDirectory(fake.runner, { mode: 0o750, path: '/opt/app/etc' }, output)).toEqual(
+      {
+        action: 'update',
+      },
+    );
+    const fixed = await reconcileDirectory(
+      fake.runner,
+      { mode: 0o750, path: '/opt/app/etc' },
+      output,
+    );
+    expect(fixed.mode).toBe(0o750);
+  });
+
+  test('a directory that is not this resource is refused unless adoption is on', async () => {
+    const fake = host();
+    await reconcileDirectory(fake.runner, { mode: 0o700, path: '/opt/app/etc' });
+    await expect(
+      reconcileDirectory(fake.runner, { mode: 0o755, path: '/opt/app/etc' }),
+    ).rejects.toThrow(/deploy with --adopt/);
+    const adopted = await reconcileDirectory(
+      fake.runner,
+      { mode: 0o755, path: '/opt/app/etc' },
+      undefined,
+      true,
+    );
+    expect(adopted.mode).toBe(0o755);
+  });
+
+  test('a directory that already matches is not touched — not even a no-op chown', async () => {
+    const fake = host();
+    const props = { group: 'app', mode: 0o755, owner: 'app', path: '/opt/app/etc' };
+    const output = await reconcileDirectory(fake.runner, props);
+    const before = fake.calls.length;
+    await reconcileDirectory(fake.runner, props, output);
+    const after = fake.calls.slice(before).map((call) => call[0]);
+    expect(after).not.toContain('mkdir');
+    expect(after).not.toContain('chmod');
+    // ⛔ A chown that changes nothing is still a write on the host and a line in the deploy log.
+    expect(after).not.toContain('chown');
+  });
+});
+
+describe('delete', () => {
+  test('is rmdir: a directory that still holds a file is a refusal', async () => {
+    const fake = host();
+    const attrs = await reconcileDirectory(fake.runner, { path: '/opt/app/etc' });
+    await fake.runner.writeFileAtomic('/opt/app/etc/kept.conf', new Uint8Array(), { mode: 0o644 });
+    await expect(deleteDirectory(fake.runner, attrs)).rejects.toThrow(/Directory not empty/);
+    expect(fake.calls.some((call) => call.includes('-r') || call.includes('-rf'))).toBe(false);
+  });
+
+  test('an empty directory goes, and a second delete is a no-op', async () => {
+    const fake = host();
+    const attrs = await reconcileDirectory(fake.runner, { path: '/opt/app/etc' });
+    await deleteDirectory(fake.runner, attrs);
+    expect(await readDirectory(fake.runner, '/opt/app/etc')).toBeUndefined();
+    await deleteDirectory(fake.runner, attrs);
+  });
+});
+
+describe('validation', () => {
+  test('refuses a relative or unnormalised path and an impossible mode', () => {
+    expect(directoryProblems({ path: 'opt/app' })).toContain('path must be absolute');
+    expect(directoryProblems({ path: '/opt/../etc' }).length).toBeGreaterThan(0);
+    expect(directoryProblems({ mode: 0o10000, path: '/opt/app' })).toContain(
+      'mode must be 0–0o7777',
+    );
+  });
+});

package/src/linux/directory.ts

@@ -0,0 +1,71 @@
+/**
+ * `Host.Directory` — one directory on the host, declared: path, mode, owner, group.
+ *
+ * ⚠️ NOTHING IS ADOPTED WITHOUT `--adopt`: a directory already at the path reads as `Unowned`, and
+ *   where the plan never asked, reconcile honours the same flag (docs/ownership.md).
+ * ★ IT IS NOT LINUX-ONLY. `mkdir`, `chmod`, `chown` and `rmdir` are the same argv on macOS, so this
+ *   resource works through any HostRunner; it lives in the linux subpath because the gap it closes
+ *   was found there (a first deploy into a new tree, which every file resource refuses to create).
+ */
+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 { HostRunnerService } from '../launchd/runner.ts';
+import { adoptsAtApply } from '../ownership/adopt.ts';
+import { noteUnfinished } from '../ownership/resume.ts';
+import type { HostDirectoryAttributes, HostDirectoryProps } from './directory-lifecycle.ts';
+import {
+  deleteDirectory,
+  diffDirectory,
+  readDirectory,
+  reconcileDirectory,
+} from './directory-lifecycle.ts';
+
+export type { HostDirectoryAttributes, HostDirectoryProps } from './directory-lifecycle.ts';
+
+export interface HostDirectory extends Resource<
+  'Host.Directory',
+  HostDirectoryProps,
+  HostDirectoryAttributes
+> {}
+
+export const HostDirectory = Resource<HostDirectory>('Host.Directory');
+
+export const HostDirectoryProvider = () =>
+  Provider.effect(
+    HostDirectory,
+    Effect.gen(function* () {
+      const runner = yield* HostRunnerService;
+      return HostDirectory.Provider.of({
+        list: () => Effect.succeed([]),
+
+        read: ({ olds, output }) =>
+          lift(async () => {
+            const found = await readDirectory(runner, olds.path);
+            if (found === undefined) return undefined;
+            return output === undefined ? Unowned(found) : found;
+          }),
+
+        diff: ({ instanceId, news, output }) => {
+          if (output === undefined) return noteUnfinished(instanceId);
+          if (isResolved(news)) return lift(() => diffDirectory(runner, news, output));
+          // ⛔ A new path is a replace even while the rest is unresolved: the engine's default
+          //   update would create the new directory and leave the old one behind forever.
+          const path = resolvedString(news, 'path');
+          return Effect.succeed(
+            path !== undefined && path !== output.path ? { action: 'replace' as const } : undefined,
+          );
+        },
+
+        reconcile: ({ fqn, instanceId, news, output }) =>
+          Effect.flatMap(adoptsAtApply({ fqn, instanceId, output }), (adopt) =>
+            lift(() => reconcileDirectory(runner, news, output, adopt)),
+          ),
+
+        delete: ({ output }) => lift(() => deleteDirectory(runner, output)),
+      });
+    }),
+  );