@homeflare/alchemy 0.6.0 → 0.8.0

package/src/caddy/providers.test.ts

@@ -0,0 +1,229 @@
+/**
+ * The Alchemy wiring: the provider built as a Layer over a fake admin API, its handlers called the
+ * way the engine calls them; caddyWithFile's registration; and the barrel, the public API.
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import * as Output from 'alchemy/Output';
+import { Stack } from 'alchemy/Stack';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { caddyAdminLayer } from './admin.ts';
+import { CaddyConfig, CaddyConfigProvider } from './config.ts';
+import { type FakeCaddy, fakeCaddy } from './fake-caddy.ts';
+import * as barrel from './index.ts';
+import { localCaddyAdmin } from './local-admin.ts';
+import { caddyWithFile } from './with-file.ts';
+
+const SITE = 'app.example.com reverse_proxy 127.0.0.1:8080';
+const ids = { fqn: 'stack/caddy', id: 'caddy', instanceId: 'i-1' };
+
+let fake: FakeCaddy | undefined;
+afterEach(() => {
+  fake?.stop();
+  fake = undefined;
+});
+
+/** A handler the provider must define; a missing one fails the test by name. */
+const handler = <F>(name: string, fn: F | undefined): F => {
+  if (fn === undefined) throw new Error(`provider has no ${name} handler`);
+  return fn;
+};
+
+const withProvider = <A>(
+  use: (p: Effect.Success<typeof CaddyConfig.Provider>) => Effect.Effect<A, unknown>,
+  address?: string,
+) => {
+  // ★ A Caddy on its default :2019 behind a forward, as in config-lifecycle.test.ts.
+  fake =
+    address === undefined
+      ? fakeCaddy({ listenPort: 2019, running: { apps: { legacy: true } } })
+      : undefined;
+  const admin = localCaddyAdmin({
+    address: address ?? (fake as FakeCaddy).address,
+    hostHeader: '127.0.0.1:2019',
+    retries: 0,
+  });
+  return Effect.runPromise(
+    Effect.gen(function* () {
+      return yield* use(yield* CaddyConfig.Provider);
+    }).pipe(Effect.provide(CaddyConfigProvider().pipe(Layer.provide(caddyAdminLayer(admin))))),
+  );
+};
+
+describe('CaddyConfigProvider', () => {
+  test('reconcile applies over its own state; delete then sends nothing at all', async () => {
+    await withProvider((provider) =>
+      Effect.gen(function* () {
+        const output = yield* provider.reconcile({
+          ...ids,
+          bindings: [] as never,
+          news: { caddyfile: SITE },
+          olds: { caddyfile: SITE },
+          // ★ State from an earlier deploy: the running `legacy` config is this stack's to replace.
+          output: { configSha256: 'earlier', endpoint: fake?.address ?? '' },
+          session: undefined as never,
+        });
+        expect(fake?.seen.some((call) => call.path === '/load')).toBe(true);
+        const before = fake?.seen.length;
+        yield* provider.delete({ ...ids, olds: { caddyfile: SITE }, output } as never);
+        // ★ Delete never unloads, never stops: not one more call reached Caddy.
+        expect(fake?.seen.length).toBe(before);
+      }),
+    );
+  });
+
+  test('diff defers to the engine with no prior output', async () => {
+    const diff = await withProvider((provider) =>
+      handler(
+        'diff',
+        provider.diff,
+      )({
+        ...ids,
+        news: { caddyfile: SITE },
+        olds: { caddyfile: SITE },
+        output: undefined,
+      } as never),
+    );
+    expect(diff).toBeUndefined();
+  });
+
+  test('an unresolved sourceFile still validates the Caddyfile at plan time', async () => {
+    const pending = Effect.succeed('/usr/local/etc/Caddyfile');
+    const output = { configSha256: 'x', endpoint: 'y' };
+    const ok = await withProvider((provider) =>
+      handler(
+        'diff',
+        provider.diff,
+      )({
+        ...ids,
+        news: { caddyfile: SITE, sourceFile: pending },
+        olds: { caddyfile: SITE },
+        output,
+      } as never),
+    );
+    expect(ok).toEqual({ action: 'update' });
+    const bad = withProvider((provider) =>
+      handler(
+        'diff',
+        provider.diff,
+      )({
+        ...ids,
+        news: { caddyfile: 'SYNTAX_ERROR', sourceFile: pending },
+        olds: { caddyfile: SITE },
+        output,
+      } as never),
+    );
+    await expect(bad).rejects.toThrow(/Error during parsing/);
+  });
+});
+
+describe('a Caddy that is down', () => {
+  /** A loopback port that just closed: connecting is refused, nothing is listening. */
+  const closedPort = () => {
+    const server = Bun.serve({ fetch: () => new Response(), hostname: '127.0.0.1', port: 0 });
+    const address = `http://127.0.0.1:${String(server.port)}`;
+    server.stop(true);
+    return address;
+  };
+  const output = { configSha256: 'x', endpoint: 'y' };
+
+  test('does not fail the plan: read finds nothing to adopt, diff plans an update', async () => {
+    const address = closedPort();
+    const probe = await withProvider(
+      (provider) =>
+        handler('read', provider.read)({ ...ids, olds: { caddyfile: SITE }, output: undefined }),
+      address,
+    );
+    expect(probe).toBeUndefined();
+    const diff = await withProvider(
+      (provider) =>
+        handler(
+          'diff',
+          provider.diff,
+        )({ ...ids, news: { caddyfile: SITE }, olds: { caddyfile: SITE }, output } as never),
+      address,
+    );
+    expect(diff).toEqual({ action: 'update' });
+  });
+
+  test('but the apply, which needs Caddy, fails loudly', async () => {
+    const applying = withProvider(
+      (provider) =>
+        provider.reconcile({
+          ...ids,
+          bindings: [] as never,
+          news: { caddyfile: SITE },
+          olds: undefined,
+          output: undefined,
+          session: undefined as never,
+        }),
+      closedPort(),
+    );
+    await expect(applying).rejects.toThrow(/Caddy admin POST \/adapt at http:\/\/127\.0\.0\.1/);
+  });
+
+  test('a bad Caddyfile still fails the plan when Caddy IS up (only unreachability is forgiven)', async () => {
+    const bad = withProvider((provider) =>
+      handler(
+        'diff',
+        provider.diff,
+      )({
+        ...ids,
+        news: { caddyfile: 'SYNTAX_ERROR' },
+        olds: { caddyfile: SITE },
+        output,
+      } as never),
+    );
+    await expect(bad).rejects.toThrow(/Error during parsing/);
+  });
+});
+
+describe('caddyWithFile', () => {
+  const stack = () => ({ actions: {}, bindings: {}, name: 'test', resources: {}, stage: 'test' });
+
+  test('declares the HostFile (retained) and a CaddyConfig ordered after it', async () => {
+    const spec = stack();
+    const { config, file } = await Effect.runPromise(
+      caddyWithFile('caddy', { caddyfile: SITE, path: '/usr/local/etc/Caddyfile' }).pipe(
+        Effect.provideService(Stack, spec as never),
+      ) as Effect.Effect<{ config: unknown; file: unknown }>,
+    );
+    expect(Object.keys(spec.resources).sort()).toEqual(['caddy', 'caddy-file']);
+    const target = config as { Props: { sourceFile: unknown }; RemovalPolicy: string };
+    // ★ An Output of the HostFile, not the literal path: that edge is what writes the file first.
+    expect(Output.isExpr(target.Props.sourceFile)).toBe(true);
+    expect(target.RemovalPolicy).toBe('retain');
+    expect((file as { RemovalPolicy: string }).RemovalPolicy).toBe('retain');
+  });
+
+  test('a literal secret is refused before the HostFile — and its content prop — exist', async () => {
+    const spec = stack();
+    const failure = Effect.runPromise(
+      Effect.flip(
+        caddyWithFile('caddy', {
+          caddyfile: 'dns cloudflare abcdef0123456789',
+          path: '/etc/Caddyfile',
+        }),
+      ).pipe(Effect.provideService(Stack, spec as never)) as Effect.Effect<Error>,
+    );
+    expect((await failure).message).toMatch(/caddyWithFile caddy: line 1/);
+    expect(spec.resources).toEqual({});
+  });
+});
+
+describe('the barrel', () => {
+  test('exports the public API and not the internals', () => {
+    expect(Object.keys(barrel).sort()).toEqual([
+      'CaddyAdminError',
+      'CaddyAdminService',
+      'CaddyConfig',
+      'CaddyConfigProvider',
+      'CaddyUnreachableError',
+      'DEFAULT_ADMIN_ADDRESS',
+      'caddyAdminLayer',
+      'caddyProviders',
+      'caddyWithFile',
+      'localCaddyAdmin',
+    ]);
+  });
+});

package/src/caddy/providers.ts

@@ -0,0 +1,17 @@
+/**
+ * The Caddy provider with its admin transport, as a single layer for a host stack.
+ *
+ *     Layer.mergeAll(caddyProviders(), launchdProviders(), …the stack's other providers)
+ *
+ * ★ launchdProviders() TOO when the stack uses caddyWithFile(): the file is a launchd-subpath
+ *   HostFile, written through that subpath's HostRunner.
+ * ⚠️ The default is localCaddyAdmin(): `http://127.0.0.1:2019`, Caddy's default admin listener.
+ *   Pass another CaddyAdmin for a unix socket, a narrowed `admin { origins }`, or an SSH forward.
+ */
+import * as Layer from 'effect/Layer';
+import { type CaddyAdmin, caddyAdminLayer } from './admin.ts';
+import { CaddyConfigProvider } from './config.ts';
+import { localCaddyAdmin } from './local-admin.ts';
+
+export const caddyProviders = (admin: CaddyAdmin = localCaddyAdmin()) =>
+  CaddyConfigProvider().pipe(Layer.provide(caddyAdminLayer(admin)));

package/src/caddy/with-file.ts

@@ -0,0 +1,66 @@
+/**
+ * `caddyWithFile` — one Caddyfile, applied to the running Caddy AND written to the file Caddy
+ * starts from, so a restart keeps it (decision 23: "the file also lands on disk").
+ *
+ * ★ REUSES launchd's HostFile, NOT A SECOND FILE WRITER. The file is an ordinary `Host.File`
+ *   (atomic write, digest diff, symlink refusal, `--adopt` for a file already there); the config is
+ *   a `Caddy.Config` whose `sourceFile` is that HostFile's `path` Output — which is what orders them.
+ *
+ * ⛔ THE ORDER IS FILE, THEN `/load`. The dependency makes Alchemy write the file first, and it is the
+ *   only order that bootstraps: a new host's Caddy launchd job starts from the file, before any
+ *   admin API exists to load into. Its cost, and what bounds it:
+ *   · A Caddyfile that does not ADAPT never reaches disk once the config has state: CaddyConfig's
+ *     diff adapts it at PLAN time and fails the plan. (On the very first deploy the file's path is
+ *     still an Output, Alchemy skips the adoption probe, and the check runs at apply instead.)
+ *   · A Caddyfile that adapts but that Caddy then REFUSES (a port in use, a missing cert file) is
+ *     on disk when `/load` fails. Caddy keeps serving the old config, the deploy fails with Caddy's
+ *     reason — and a Caddy started without `--resume` would load the refused file on its next
+ *     restart. Managed Caddies run with `--resume` (decision, 2026-09-21; docs/caddy.md): they
+ *     restart from `autosave.json`, the last config Caddy ACCEPTED, and the file is only the
+ *     first-boot fallback.
+ *   · The skipped probe is also why the ADOPTION check of a first deploy happens at apply: a Caddy
+ *     running a config this stack did not load is refused before `/load` unless the deploy runs
+ *     with `--adopt` (config-lifecycle.ts reconcileConfig) — after this file is written.
+ * ⛔ SECRETS ARE REFUSED HERE, AT DECLARATION, before the HostFile exists: its `content` is a prop
+ *   too, and would carry a literal into state even if the CaddyConfig then refused it.
+ * ★ BOTH RETAIN. Removing this from a stack must not delete the file a restart needs.
+ */
+import * as Effect from 'effect/Effect';
+import * as RemovalPolicy from 'alchemy/RemovalPolicy';
+import { HostFile } from '../launchd/host-file.ts';
+import { CaddyConfig } from './config.ts';
+import { configProblems } from './config-form.ts';
+
+export interface CaddyWithFileProps {
+  /** The whole Caddyfile. ⛔ Never a secret — use `{env.NAME}` / `{file./path}` placeholders. */
+  readonly caddyfile: string;
+  /** Absolute path Caddy is started with: `caddy run --config <path> --adapter caddyfile`. */
+  readonly path: string;
+  /** @default 0o644 */
+  readonly mode?: number;
+  readonly owner?: string | number;
+  readonly group?: string | number;
+}
+
+/**
+ * Declare the file (`<id>-file`) and the config (`<id>`). Provide `launchdProviders()` for the
+ * file and `caddyProviders()` for the config.
+ *
+ *     const { config, file } = yield* caddyWithFile('caddy', { caddyfile, path: '/usr/local/etc/Caddyfile' });
+ */
+export const caddyWithFile = (id: string, props: CaddyWithFileProps) =>
+  Effect.gen(function* () {
+    const found = configProblems({ caddyfile: props.caddyfile, sourceFile: props.path });
+    if (found.length > 0) {
+      return yield* Effect.fail(new Error(`caddyWithFile ${id}: ${found.join('; ')}`));
+    }
+    const file = yield* HostFile(`${id}-file`, {
+      content: props.caddyfile,
+      mode: props.mode ?? 0o644,
+      path: props.path,
+      ...(props.owner === undefined ? {} : { owner: props.owner }),
+      ...(props.group === undefined ? {} : { group: props.group }),
+    }).pipe(RemovalPolicy.retain());
+    const config = yield* CaddyConfig(id, { caddyfile: props.caddyfile, sourceFile: file.path });
+    return { config, file };
+  });

package/src/cloudflare/fake-mesh.ts

@@ -0,0 +1,181 @@
+/**
+ * A fake Cloudflare `warp_connector` API for the MeshNode tests — an in-memory `fetch` handed to
+ * Effect's real FetchHttpClient through its `Fetch` reference, so the tests exercise distilled's
+ * real path assembly, query and body encoding, envelope decoding and error matching.
+ *
+ * ⛔ TEST-ONLY, AND NO NETWORK. No provider imports this file. The base URL is RFC 2606
+ *   `api.example.com`, and any request outside `/accounts/<FAKE_ACCOUNT>/warp_connector` throws, so
+ *   a mis-wired test fails instead of reaching a real API. The credentials are placeholders.
+ * ★ THE NAME FILTER IS A SUBSTRING MATCH ON PURPOSE. The real filter's exactness is undocumented;
+ *   a loose fake proves the client re-checks the exact name.
+ * ★ PAGES OF TWO by default, so every lookup walks more than one page.
+ * ★ `is_deleted` IS HONOURED AS THE SDK DOCUMENTS IT: `false` → live only, `true` → deleted only,
+ *   absent → every tunnel. So a lookup that forgot the filter sees tombstones and must drop them.
+ * ★ `onCreate` runs before a POST is answered: a test uses it to put a node in the way between
+ *   the provider's lookup and its create — what a retried POST whose first response was lost does.
+ */
+import { type Credentials, fromApiToken } from '@distilled.cloud/cloudflare/Credentials';
+import * as Cloudflare from 'alchemy/Cloudflare';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Redacted from 'effect/Redacted';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+
+export const FAKE_BASE = 'https://api.example.com/client/v4';
+export const FAKE_ACCOUNT = '00000000000000000000000000000001';
+/** ⚠️ A placeholder, not a credential. Tests assert it is what the SDK sends. */
+export const FAKE_API_TOKEN = 'placeholder-api-token';
+
+export type FakeNode = {
+  id: string;
+  name: string;
+  ha: boolean;
+  status: string;
+  token: string;
+  deleted_at: string | null;
+};
+
+export type Seen = { readonly method: string; readonly path: string; readonly body: unknown };
+
+const ok = (result: unknown, extra: Record<string, unknown> = {}) =>
+  Response.json({ success: true, errors: [], messages: [], result, ...extra });
+
+export const fakeFailure = (status: number, code: number, message: string) =>
+  Response.json(
+    { success: false, errors: [{ code, message }], messages: [], result: null },
+    { status },
+  );
+
+/** The wire shape of a node, as the API documents it — plus `token` on create, as the HA page says. */
+const wire = (node: FakeNode) => ({
+  id: node.id,
+  account_tag: FAKE_ACCOUNT,
+  created_at: '2026-09-21T00:00:00Z',
+  deleted_at: node.deleted_at,
+  name: node.name,
+  status: node.status,
+  tun_type: 'warp_connector',
+});
+
+export type FakeOptions = {
+  readonly perPage?: number;
+  /** Return a Response to answer the POST with it instead (e.g. `fakeFailure(409, 1013, …)`). */
+  readonly onCreate?: (name: string) => Response | void;
+};
+
+export const fakeMesh = (options: FakeOptions = {}) => {
+  const nodes = new Map<string, FakeNode>();
+  const seen: Seen[] = [];
+  const auth: string[] = [];
+  let next = 1;
+  const live = () => [...nodes.values()].filter((node) => node.deleted_at === null);
+  const listed = (isDeleted: string | null) =>
+    [...nodes.values()].filter((node) =>
+      isDeleted === null ? true : (node.deleted_at !== null) === (isDeleted === 'true'),
+    );
+
+  const seed = (node: Partial<FakeNode> & { name: string }): FakeNode => {
+    const id = node.id ?? `00000000-0000-4000-8000-${String(next++).padStart(12, '0')}`;
+    const full: FakeNode = {
+      id,
+      ha: false,
+      status: 'inactive',
+      token: `fake-node-token-${id}`,
+      deleted_at: null,
+      ...node,
+    };
+    nodes.set(id, full);
+    return full;
+  };
+
+  const route = (method: string, url: URL, body: Record<string, unknown>): Response => {
+    const prefix = `/client/v4/accounts/${FAKE_ACCOUNT}/warp_connector`;
+    if (url.host !== 'api.example.com' || !url.pathname.startsWith(prefix)) {
+      throw new Error(`fake-mesh: unexpected request ${method} ${url.href}`);
+    }
+    const [id, sub] = url.pathname.slice(prefix.length).split('/').filter(Boolean);
+    if (id === undefined && method === 'GET') {
+      const filter = url.searchParams.get('name') ?? '';
+      const page = Number(url.searchParams.get('page') ?? '1');
+      const perPage = Number(url.searchParams.get('per_page') ?? options.perPage ?? 2);
+      const hits = listed(url.searchParams.get('is_deleted')).filter((node) =>
+        node.name.includes(filter),
+      );
+      const slice = hits.slice((page - 1) * perPage, page * perPage);
+      return ok(slice.map(wire), { result_info: { page, per_page: perPage, count: slice.length } });
+    }
+    if (id === undefined && method === 'POST') {
+      const name = String(body['name']);
+      const override = options.onCreate?.(name);
+      if (override !== undefined) return override;
+      if (live().some((node) => node.name === name)) {
+        return fakeFailure(409, 1013, 'Tunnel with name already exists');
+      }
+      const node = seed({ name, ha: body['ha'] === true });
+      return ok({ ...wire(node), token: node.token });
+    }
+    const node = id === undefined ? undefined : nodes.get(id);
+    if (node === undefined) return fakeFailure(404, 1002, 'Tunnel not found');
+    if (sub === 'token' && method === 'GET') return ok(node.token);
+    if (sub !== undefined) throw new Error(`fake-mesh: unexpected ${method} ${url.pathname}`);
+    if (method === 'GET') return ok(wire(node));
+    if (method === 'PATCH') {
+      const name = String(body['name']);
+      if (live().some((other) => other.name === name && other.id !== node.id)) {
+        return fakeFailure(409, 1013, 'Tunnel with name already exists');
+      }
+      node.name = name;
+      return ok(wire(node));
+    }
+    if (method === 'DELETE') {
+      if (node.deleted_at !== null) return fakeFailure(404, 1002, 'Tunnel not found');
+      node.deleted_at = '2026-09-21T01:00:00Z';
+      return ok(wire(node));
+    }
+    throw new Error(`fake-mesh: unexpected ${method} ${url.pathname}`);
+  };
+
+  const fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const url = new URL(request.url);
+    const text = await request.text();
+    const body = text.length === 0 ? {} : (JSON.parse(text) as Record<string, unknown>);
+    seen.push({ method: request.method, path: `${url.pathname}${url.search}`, body });
+    auth.push(request.headers.get('authorization') ?? '');
+    return route(request.method, url, body);
+  }) as typeof globalThis.fetch;
+
+  return { auth, fetch, live, nodes, seed, seen };
+};
+
+export type FakeMesh = ReturnType<typeof fakeMesh>;
+
+/** distilled Credentials + the real FetchHttpClient over the fake — what a Bun script provides. */
+export const fakeClientLayer = (
+  fake: FakeMesh,
+  credentials: Layer.Layer<Credentials> = fromApiToken({
+    apiToken: FAKE_API_TOKEN,
+    apiBaseUrl: FAKE_BASE,
+  }),
+) =>
+  Layer.mergeAll(
+    credentials,
+    FetchHttpClient.layer,
+    Layer.succeed(FetchHttpClient.Fetch, fake.fetch),
+  );
+
+/** …plus the account, as Alchemy's CloudflareEnvironment hands it to a provider. */
+export const fakeProviderLayer = (fake: FakeMesh, accountId: string = FAKE_ACCOUNT) =>
+  Layer.mergeAll(
+    fakeClientLayer(fake),
+    Layer.succeed(
+      Cloudflare.CloudflareEnvironment,
+      Effect.succeed({
+        type: 'apiToken' as const,
+        apiToken: Redacted.make(FAKE_API_TOKEN),
+        accountId,
+        source: { type: 'env' as const },
+      }),
+    ),
+  );

package/src/cloudflare/index.ts

@@ -1,12 +1,18 @@
 /**
  * Cloudflare providers for Alchemy — the gaps the vendor SDK leaves.
  *
- * ★ Built on the official `cloudflare` SDK, not hand-rolled HTTP: it already has
- *   `r2.buckets.locks.update/get` over the documented endpoints, so there is no path
- *   string this package invents.
+ * ★ Built on vendor SDKs, not hand-rolled HTTP. `R2BucketLock` uses the official `cloudflare`
+ *   SDK, which already has `r2.buckets.locks.update/get` over the documented endpoints.
+ *   `MeshNode` uses `@distilled.cloud/cloudflare`, the SDK Alchemy's own Cloudflare providers
+ *   use, because `cloudflare@4.5.0` cannot create an HA node (mesh-node-api.ts). Either way
+ *   there is no path string this package invents.
  */
 export type { R2LockRule } from './lock-rules.ts';
 export { R2BucketLock, type R2BucketLockProps } from './r2-bucket-lock.ts';
+export { MeshNode, MeshNodeProvider, type MeshNodeServices } from './mesh-node.ts';
+export type { MeshNodeAttributes, MeshNodeProps } from './mesh-node-form.ts';
+export { MeshNodeError, type MeshNodeStatus } from './mesh-node-api.ts';
+export { fetchMeshNodeToken, type MeshNodeRef } from './mesh-node-token.ts';
 export { providers } from './providers.ts';
 export {
   astroWebsite,

package/src/cloudflare/mesh-node-api.ts

@@ -0,0 +1,127 @@
+/**
+ * The `warp_connector` calls a Cloudflare Mesh node needs, and nothing else.
+ *
+ * ★ A MESH NODE IS A `warp_connector` OBJECT. Cloudflare's Mesh docs create one with
+ *   `POST /accounts/{account_id}/warp_connector` and fetch its enrolment token from
+ *   `GET …/warp_connector/{id}/token` (developers.cloudflare.com/mesh/get-started, read
+ *   2026-09-21). There is no separate "mesh node" endpoint.
+ *
+ * ★ OVER `@distilled.cloud/cloudflare`, THE SDK ALCHEMY'S OWN CLOUDFLARE PROVIDERS USE, not the
+ *   `cloudflare` npm SDK the R2 lock uses. Measured 2026-09-21: `cloudflare@4.5.0`'s
+ *   `WARPConnectorCreateParams` has only `account_id` and `name`, so it cannot create an HA node.
+ *   distilled `1.0.0-rc.12` (the version alchemy@2.0.0-beta.79 pins) has `ha?: boolean` on
+ *   `CreateTunnelWarpConnectorRequest`, typed errors (`TunnelNotFound` code 1002 / 404,
+ *   `DuplicateTunnelName` code 1013), and resolves credentials and the account exactly the way
+ *   `Cloudflare.Tunnel.WarpConnector` and `Cloudflare.Gateway.Rule` do — so the node and the Gateway
+ *   rules that pin its Mesh IP always land in the same account.
+ *
+ * ⛔ NO FUNCTION IN THIS FILE READS THE NODE TOKEN, and `observe` copies named fields only. The
+ *   HA docs say the create response carries a `token` field; distilled's decoder copies only the
+ *   fields in its schema (protocol.ts, `getProps(outputAst)`), and `observe` below would drop it
+ *   again if it ever got through. The one token read lives in mesh-node-token.ts, on demand.
+ */
+import * as zeroTrust from '@distilled.cloud/cloudflare/zero-trust';
+import * as Data from 'effect/Data';
+import * as Effect from 'effect/Effect';
+import * as Stream from 'effect/Stream';
+
+/** `inactive` (never run), `degraded`, `healthy` or `down` — Cloudflare's own four. */
+export type MeshNodeStatus = 'inactive' | 'degraded' | 'healthy' | 'down';
+
+/** A live node as this package sees it. ⛔ There is no token field here, on purpose. */
+export interface ObservedNode {
+  readonly id: string;
+  readonly name: string;
+  readonly status: MeshNodeStatus | undefined;
+}
+
+/** A refusal or failure, carrying the sentence an operator needs. Never a token. */
+export class MeshNodeError extends Data.TaggedError('MeshNodeError')<{
+  readonly message: string;
+}> {}
+
+type Raw = {
+  readonly id?: string | null;
+  readonly name?: string | null;
+  readonly status?: string | null;
+  readonly deletedAt?: string | null;
+};
+
+const STATUSES: readonly string[] = ['inactive', 'degraded', 'healthy', 'down'];
+
+/**
+ * ⚠️ A DELETED NODE IS NOT A NODE. Cloudflare keeps deleted tunnels (every response carries
+ *   `deleted_at`, and the list takes `is_deleted`), so a `GET` by id can answer for one. Treating
+ *   that as live would "adopt" a tombstone and PATCH it.
+ */
+export const observe = (raw: Raw): ObservedNode | undefined => {
+  if (typeof raw.id !== 'string' || raw.id.length === 0) return undefined;
+  if (raw.deletedAt !== undefined && raw.deletedAt !== null) return undefined;
+  const status =
+    typeof raw.status === 'string' && STATUSES.includes(raw.status)
+      ? (raw.status as MeshNodeStatus)
+      : undefined;
+  return { id: raw.id, name: raw.name ?? '', status };
+};
+
+/** The node with this id, or `undefined` when it is gone (404 / code 1002, or soft-deleted). */
+export const getNode = (accountId: string, nodeId: string) =>
+  zeroTrust.getTunnelWarpConnector({ accountId, tunnelId: nodeId }).pipe(
+    Effect.map(observe),
+    Effect.catchTag('TunnelNotFound', () => Effect.succeed(undefined)),
+  );
+
+/**
+ * The live node with exactly this name, or `undefined`.
+ *
+ * ★ `name` is also sent as the list filter, but the match is re-checked here: the filter's
+ *   exactness is not documented, and a prefix match would adopt the wrong node.
+ * ⛔ Two live matches is refused rather than resolved. Names are unique per account (the create
+ *   answers code 1013 otherwise), so two means something this package does not understand.
+ */
+export const findNodeByName = (accountId: string, name: string) =>
+  zeroTrust.listTunnelWarpConnectors.items({ accountId, name, isDeleted: false }).pipe(
+    Stream.map(observe),
+    Stream.filter((node): node is ObservedNode => node !== undefined && node.name === name),
+    Stream.runCollect,
+    Effect.flatMap((chunk) => {
+      const matches = Array.from(chunk);
+      if (matches.length <= 1) return Effect.succeed(matches[0]);
+      const ids = matches.map((node) => node.id).join(', ');
+      return Effect.fail(
+        new MeshNodeError({
+          message: `Mesh node name "${name}" matches ${matches.length} live nodes (${ids}). Names are unique per account, so refusing to guess which one is meant.`,
+        }),
+      );
+    }),
+  );
+
+/**
+ * ⛔ `ha` IS SENT ON CREATE AND NOWHERE ELSE. Cloudflare's HA page: "High availability is set at
+ *   node creation time and cannot be changed afterward." The PATCH body (`PatchTunnelWarpConnector
+ *   Request`) has only `name` and `tunnelSecret`.
+ */
+export const createNode = (accountId: string, name: string, ha: boolean) =>
+  zeroTrust.createTunnelWarpConnector({ accountId, name, ha }).pipe(
+    Effect.flatMap((raw) => {
+      const node = observe(raw);
+      return node === undefined
+        ? Effect.fail(
+            new MeshNodeError({ message: `Creating Mesh node "${name}" returned no id.` }),
+          )
+        : Effect.succeed(node);
+    }),
+  );
+
+/** ★ A rename is a PATCH: same id, same token, same enrolled replicas and Mesh IP. */
+export const renameNode = (accountId: string, nodeId: string, name: string) =>
+  zeroTrust
+    .patchTunnelWarpConnector({ accountId, tunnelId: nodeId, name })
+    .pipe(Effect.map((raw) => observe(raw) ?? { id: nodeId, name, status: undefined }));
+
+/** Idempotent: a node already gone (404 / code 1002) is a successful delete. */
+export const deleteNode = (accountId: string, nodeId: string) =>
+  zeroTrust.deleteTunnelWarpConnector({ accountId, tunnelId: nodeId }).pipe(
+    Effect.asVoid,
+    Effect.catchTag('TunnelNotFound', () => Effect.void),
+  );