@homeflare/alchemy 0.20.0 → 0.21.0

package/src/cloudflare/mcp-server-api.ts

@@ -0,0 +1,294 @@
+/**
+ * The Access **AI Controls MCP server** calls a portal entry needs, and nothing else.
+ *
+ * ★ A PORTAL ENTRY IS ITS OWN OBJECT, NOT AN ACCESS APPLICATION. Cloudflare's MCP server portals
+ *   model one upstream server as THREE objects: this one
+ *   (`/accounts/{account_id}/access/ai-controls/mcp/servers`), the portal that aggregates it, and
+ *   an Access application of type `mcp` whose only destination is
+ *   `{ type: "via_mcp_server_portal", mcp_server_id: <this id> }`, which carries the policies that
+ *   decide who SEES the server in the portal (developers.cloudflare.com/cloudflare-one/
+ *   access-controls/ai-controls/secure-mcp-servers/ and .../mcp-portals/, read 2026-09-22).
+ *   Alchemy beta.79 ships `Cloudflare.Access.McpPortal` for the second and says in its own doc
+ *   comment that the first is "managed out of band (a future `Cloudflare.Access.McpServer`
+ *   resource)". This is that resource; mcp-access-app.ts covers the third.
+ *
+ * ★ OVER `@distilled.cloud/cloudflare`, THE SDK ALCHEMY'S OWN CLOUDFLARE PROVIDERS USE. Measured
+ *   2026-09-22: the official `cloudflare` npm SDK 4.5.0 has no AI Controls resources at all — its
+ *   `src/resources/zero-trust/` stops at access/devices/dex/dlp/gateway/identity-providers/
+ *   networks/organizations/risk-scoring/tunnels — while distilled `1.0.0-rc.12` carries all six
+ *   verbs used below. So there is no path string this file invents.
+ *
+ * ⛔ THE SERVER ID IS CLIENT-SUPPLIED AND REQUIRED ON CREATE. `CreateAccessAiControlMcpServer
+ *   Request.id` is a request field, not a server-generated one, which is why the resource takes it
+ *   as a required prop: the Access application that governs the entry names the SAME id in its
+ *   destination, so a generated id would have to be read back before the app could be declared.
+ *
+ * ⛔ NO TYPED `NotFound` EXISTS FOR THESE OPERATIONS. Measured 2026-09-22: every MCP-server verb
+ *   declares its error channel as the bare `CloudflareOpError`, whose `DefaultErrors` are
+ *   Unauthorized / TooManyRequests / InternalServerError / BadGateway / ServiceUnavailable /
+ *   GatewayTimeout — `NotFound` and `Forbidden` are NOT in the union, though distilled's protocol
+ *   constructs both at runtime from `HTTP_STATUS_MAP` (protocol.js, the 4xx branch). So "gone" is
+ *   matched on the runtime `_tag` through `Effect.catchIf`; `Effect.catchTag('NotFound', …)` does
+ *   not typecheck here, and a reviewer who "fixes" it to `catchTag` breaks the build, not the
+ *   behaviour.
+ */
+import * as zeroTrust from '@distilled.cloud/cloudflare/zero-trust';
+import * as Data from 'effect/Data';
+import * as Effect from 'effect/Effect';
+import * as Predicate from 'effect/Predicate';
+import * as Stream from 'effect/Stream';
+
+/** How the portal authenticates to the upstream MCP server. */
+export type McpServerAuthType = 'oauth' | 'bearer' | 'unauthenticated';
+
+/** Cloudflare's four sync states for a portal entry's tool/prompt catalog. */
+export type McpServerStatus = 'waiting' | 'ready' | 'stale' | 'error';
+
+/** Whether an administrator still has to authenticate before a catalog sync can succeed. */
+export type McpServerAuthenticationStatus =
+  | 'not_required'
+  | 'required'
+  | 'connected'
+  | 'stale'
+  | 'manual';
+
+/** A server-wide override for one tool or prompt the upstream server advertises. */
+export interface McpCapabilityOverride {
+  /** Name of the upstream capability being overridden. */
+  readonly name: string;
+  /** Custom name exposed through the portal. */
+  readonly alias?: string;
+  /** Custom description exposed through the portal. */
+  readonly description?: string;
+  /** Whether the capability is available through the portal at all. */
+  readonly enabled?: boolean;
+}
+
+/** A live portal entry as this package sees it. ⛔ There is no credential field here, on purpose. */
+export interface ObservedServer {
+  readonly id: string;
+  readonly name: string;
+  readonly hostname: string;
+  readonly authType: McpServerAuthType;
+  readonly description: string | undefined;
+  readonly isSharedOauthCallbackEnabled: boolean;
+  readonly secureWebGateway: boolean;
+  readonly status: McpServerStatus | undefined;
+  readonly authenticationStatus: McpServerAuthenticationStatus | undefined;
+  readonly lastSynced: string | undefined;
+  readonly createdAt: string | undefined;
+}
+
+/** A refusal or failure, carrying the sentence an operator needs. Never a credential. */
+export class McpServerError extends Data.TaggedError('McpServerError')<{
+  readonly message: string;
+}> {}
+
+type Raw = {
+  readonly id?: string | null;
+  readonly name?: string | null;
+  readonly hostname?: string | null;
+  readonly authType?: string | null;
+  readonly description?: string | null;
+  readonly isSharedOauthCallbackEnabled?: boolean | null;
+  readonly secureWebGateway?: boolean | null;
+  readonly status?: string | null;
+  readonly authenticationStatus?: string | null;
+  readonly lastSynced?: string | null;
+  readonly createdAt?: string | null;
+};
+
+const AUTH_TYPES: readonly string[] = ['oauth', 'bearer', 'unauthenticated'];
+const STATUSES: readonly string[] = ['waiting', 'ready', 'stale', 'error'];
+const AUTHENTICATION_STATUSES: readonly string[] = [
+  'not_required',
+  'required',
+  'connected',
+  'stale',
+  'manual',
+];
+
+const oneOf = <T extends string>(allowed: readonly string[], value: unknown): T | undefined =>
+  typeof value === 'string' && allowed.includes(value) ? (value as T) : undefined;
+
+/**
+ * ⚠️ AN UNRECOGNISED `auth_type` IS NOT A PORTAL ENTRY THIS RESOURCE UNDERSTANDS. The field is
+ *   required on every documented response, so `undefined` means Cloudflare grew a fourth mode —
+ *   dropping the row is safer than recording a value the diff would then compare against.
+ */
+export const observe = (raw: Raw): ObservedServer | undefined => {
+  if (typeof raw.id !== 'string' || raw.id.length === 0) return undefined;
+  const authType = oneOf<McpServerAuthType>(AUTH_TYPES, raw.authType);
+  if (authType === undefined) return undefined;
+  return {
+    id: raw.id,
+    name: raw.name ?? '',
+    hostname: raw.hostname ?? '',
+    authType,
+    description: raw.description || undefined,
+    isSharedOauthCallbackEnabled: raw.isSharedOauthCallbackEnabled ?? false,
+    secureWebGateway: raw.secureWebGateway ?? false,
+    status: oneOf<McpServerStatus>(STATUSES, raw.status),
+    authenticationStatus: oneOf<McpServerAuthenticationStatus>(
+      AUTHENTICATION_STATUSES,
+      raw.authenticationStatus,
+    ),
+    lastSynced: raw.lastSynced ?? undefined,
+    createdAt: raw.createdAt ?? undefined,
+  };
+};
+
+const tagged = (tag: string) => (error: unknown) =>
+  Predicate.hasProperty(error, '_tag') && error['_tag'] === tag;
+
+const isNotFound = tagged('NotFound');
+const isForbidden = tagged('Forbidden');
+
+/**
+ * ⛔ `Forbidden` HERE MEANS "NO AI CONTROLS ENTITLEMENT", NOT "WRONG TOKEN". Alchemy's own
+ *   `McpPortal` treats a 403 on its LIST as "this account has no portals"; on a read or a write
+ *   that would hide the one fact an operator needs, so it is turned into a sentence instead.
+ */
+const entitlement = (what: string) =>
+  new McpServerError({
+    message:
+      `Cloudflare refused ${what} with 403. On the AI Controls MCP endpoints that means the ` +
+      'account does not have the entitlement (the product is in open beta and must be enabled ' +
+      'for the account), not that the API token is wrong — a wrong token answers 401.',
+  });
+
+const withEntitlement = <A, E, R>(what: string, effect: Effect.Effect<A, E, R>) =>
+  effect.pipe(Effect.catchIf(isForbidden, () => Effect.fail(entitlement(what))));
+
+/** The portal entry with this id, or `undefined` when it does not exist. */
+export const getServer = (
+  accountId: string,
+  serverId: string,
+): Effect.Effect<ObservedServer | undefined, unknown, zeroTrust.CloudflareOpContext> =>
+  withEntitlement(
+    `reading MCP server "${serverId}"`,
+    zeroTrust.readAccessAiControlMcpServer({ accountId, id: serverId }).pipe(Effect.map(observe)),
+  ).pipe(Effect.catchIf(isNotFound, () => Effect.succeed(undefined)));
+
+/** Every portal entry in the account. ⚠️ An account without the entitlement has none. */
+export const listServers = (
+  accountId: string,
+): Effect.Effect<readonly ObservedServer[], unknown, zeroTrust.CloudflareOpContext> =>
+  zeroTrust.listAccessAiControlMcpServers.items({ accountId }).pipe(
+    Stream.map(observe),
+    Stream.filter((server): server is ObservedServer => server !== undefined),
+    Stream.runCollect,
+    Effect.map((chunk) => Array.from(chunk)),
+    Effect.catchIf(isForbidden, () => Effect.succeed([] as readonly ObservedServer[])),
+  );
+
+/** The fields a create carries beyond the identity. `undefined` keys are omitted, never sent. */
+export interface ServerWrite {
+  readonly name: string;
+  readonly description?: string;
+  readonly isSharedOauthCallbackEnabled?: boolean;
+  readonly secureWebGateway?: boolean;
+  readonly updatedTools?: readonly McpCapabilityOverride[];
+  readonly updatedPrompts?: readonly McpCapabilityOverride[];
+  /** Resolved at call time from the deploying process's environment. Never stored. */
+  readonly authCredentials?: string;
+  /** Resolved at call time from the deploying process's environment. Never stored. */
+  readonly clientSecret?: string;
+}
+
+const optional = (write: ServerWrite) => ({
+  ...(write.description === undefined ? {} : { description: write.description }),
+  ...(write.isSharedOauthCallbackEnabled === undefined
+    ? {}
+    : { isSharedOauthCallbackEnabled: write.isSharedOauthCallbackEnabled }),
+  ...(write.secureWebGateway === undefined ? {} : { secureWebGateway: write.secureWebGateway }),
+  ...(write.updatedTools === undefined ? {} : { updatedTools: [...write.updatedTools] }),
+  ...(write.updatedPrompts === undefined ? {} : { updatedPrompts: [...write.updatedPrompts] }),
+  ...(write.authCredentials === undefined ? {} : { authCredentials: write.authCredentials }),
+  ...(write.clientSecret === undefined ? {} : { clientSecret: write.clientSecret }),
+});
+
+/**
+ * ⛔ `hostname` AND `authType` ARE SENT ON CREATE AND NOWHERE ELSE. Measured 2026-09-22 against
+ *   the SDK: `UpdateAccessAiControlMcpServerRequest` carries `authCredentials`, `clientSecret`,
+ *   `description`, `isSharedOauthCallbackEnabled`, `name`, `secureWebGateway`, `updatedPrompts`
+ *   and `updatedTools` — and NEITHER `hostname` NOR `authType`. So changing either is a replace,
+ *   not an update, and mcp-server-form.ts says so in `diff`.
+ */
+export const createServer = (
+  accountId: string,
+  serverId: string,
+  hostname: string,
+  authType: McpServerAuthType,
+  write: ServerWrite,
+): Effect.Effect<ObservedServer, unknown, zeroTrust.CloudflareOpContext> =>
+  withEntitlement(
+    `creating MCP server "${serverId}"`,
+    zeroTrust
+      .createAccessAiControlMcpServer({
+        accountId,
+        id: serverId,
+        hostname,
+        authType,
+        name: write.name,
+        ...optional(write),
+      })
+      .pipe(
+        Effect.flatMap((raw) => {
+          const server = observe(raw);
+          return server === undefined
+            ? Effect.fail(
+                new McpServerError({
+                  message: `Creating MCP server "${serverId}" returned no id or an unknown auth_type.`,
+                }),
+              )
+            : Effect.succeed(server);
+        }),
+      ),
+  );
+
+/** An in-place update of the mutable fields. The identity, hostname and auth type never move. */
+export const updateServer = (
+  accountId: string,
+  serverId: string,
+  write: ServerWrite,
+): Effect.Effect<ObservedServer | undefined, unknown, zeroTrust.CloudflareOpContext> =>
+  withEntitlement(
+    `updating MCP server "${serverId}"`,
+    zeroTrust
+      .updateAccessAiControlMcpServer({
+        accountId,
+        id: serverId,
+        name: write.name,
+        ...optional(write),
+      })
+      .pipe(Effect.map(observe)),
+  );
+
+/**
+ * Refresh the entry's tool and prompt catalog from the upstream server.
+ *
+ * ⛔ BEST EFFORT, AND THE DEPLOY NEVER FAILS ON IT. An `oauth` entry reports
+ *   `authentication_status: "required"` until an administrator completes the upstream OAuth flow
+ *   in the dashboard, and a sync before that cannot succeed. Failing the create over it would make
+ *   the FIRST deploy of every Access-protected MCP server red while the object it created is
+ *   correct. The observed `status` is recorded instead, so a plan shows `waiting` or `error`.
+ */
+export const syncServer = (
+  accountId: string,
+  serverId: string,
+): Effect.Effect<McpServerStatus | undefined, never, zeroTrust.CloudflareOpContext> =>
+  zeroTrust.syncAccessAiControlMcpServer({ accountId, id: serverId }).pipe(
+    Effect.map((raw) => oneOf<McpServerStatus>(STATUSES, raw.status)),
+    Effect.catchCause(() => Effect.succeed(undefined)),
+  );
+
+/** Idempotent: an entry already gone is a successful delete. */
+export const deleteServer = (
+  accountId: string,
+  serverId: string,
+): Effect.Effect<void, unknown, zeroTrust.CloudflareOpContext> =>
+  withEntitlement(
+    `deleting MCP server "${serverId}"`,
+    zeroTrust.deleteAccessAiControlMcpServer({ accountId, id: serverId }).pipe(Effect.asVoid),
+  ).pipe(Effect.catchIf(isNotFound, () => Effect.void));

package/src/cloudflare/mcp-server-form.ts

@@ -0,0 +1,219 @@
+/**
+ * `Cloudflare.McpServer` — its props, its attributes, and the pure `diff` that decides between
+ * update and replace.
+ *
+ * ⛔ THE ATTRIBUTES NEVER HOLD A CREDENTIAL. `auth_credentials` and `client_secret` are write-only
+ *   at the API (the read endpoints return an `auth_config_summary` that never includes the secret
+ *   value), and Alchemy's state store is not encrypted — `StateEncoding.ts` TAGS a `Redacted`
+ *   value and writes the inner value beside the tag, so `Redacted` hides a secret from a log line
+ *   and from nothing else. So both are declared as `{ fromEnv: 'NAME' }` (secrets/write-only.ts),
+ *   the NAME lands in state, and the value exists only in the deploying process and on the wire.
+ * ★ AND A PLAN STILL NOTICES A CHANGE, because what was last written is remembered as a salted
+ *   scrypt SEAL, the same mechanism the PBS notification targets use.
+ */
+import type { Diff } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import type { FromEnv } from '../secrets/write-only.ts';
+import {
+  type McpCapabilityOverride,
+  type McpServerAuthType,
+  type McpServerAuthenticationStatus,
+  McpServerError,
+  type McpServerStatus,
+} from './mcp-server-api.ts';
+
+export interface McpServerProps {
+  /**
+   * The entry's id in the account — client-supplied, required, and the identity everything else
+   * names. ⛔ Changing it REPLACES the entry, because the id is what the governing Access
+   * application's `{ type: 'via_mcp_server_portal', mcpServerId }` destination points at.
+   * ★ Required rather than generated: a generated id would have to be read back out of state
+   *   before that application could be declared, which is the opposite of a declaration.
+   */
+  readonly serverId: string;
+  /** Display name in the portal. Defaults to the id. */
+  readonly name?: string;
+  /**
+   * The FULL upstream MCP endpoint URL, including its path — `https://example.com/mcp`, not
+   * `example.com`. ⚠️ THE FIELD IS NAMED `hostname` AND IS NOT ONE; Cloudflare's own API doc
+   * calls it "URL of the upstream MCP endpoint". A bare host is refused by `validateMcpServer`
+   * rather than sent, because the portal would then fetch `https:///` and report a sync error
+   * that reads like the upstream server being down.
+   * ⛔ CREATE-ONLY: the update request has no `hostname`, so a change is a replace.
+   * ⚠️ The upstream hostname must be PROXIED in Cloudflare DNS for a portal to reach it
+   *   (developers.cloudflare.com/cloudflare-one/access-controls/ai-controls/mcp-portals/).
+   */
+  readonly hostname: string;
+  /**
+   * How the portal authenticates to the upstream server.
+   * ⛔ CREATE-ONLY, like `hostname`, and required for that reason — a default would silently fix
+   *   a choice that can only be changed by replacing the entry.
+   * - `oauth` — the upstream server is its own OAuth resource (including one fronted by
+   *   Cloudflare Access managed OAuth). The portal registers itself; no static secret here.
+   * - `bearer` — a static credential, declared as `authCredentials`.
+   * - `unauthenticated` — no credential at all.
+   */
+  readonly authType: McpServerAuthType;
+  /**
+   * The static credential for `authType: 'bearer'`, by the NAME of the environment variable
+   * holding it. Either a raw token, or a JSON object `{"headers":{…}}` for custom headers — which
+   * is how an Access service token pair (`cf-access-client-id` / `cf-access-client-secret`) is
+   * sent, per Cloudflare's own example.
+   */
+  readonly authCredentials?: FromEnv;
+  /** The pre-registered OAuth client secret for a manual-mode `oauth` entry, by variable name. */
+  readonly clientSecret?: FromEnv;
+  readonly description?: string;
+  /**
+   * Use Cloudflare's shared OAuth callback instead of the portal hostname's. Server default off.
+   */
+  readonly isSharedOauthCallbackEnabled?: boolean;
+  /** Route the portal's outbound traffic to this server through the Secure Web Gateway. */
+  readonly secureWebGateway?: boolean;
+  /** Server-wide tool overrides — rename, re-describe or disable an upstream tool. */
+  readonly updatedTools?: readonly McpCapabilityOverride[];
+  /** Server-wide prompt overrides. */
+  readonly updatedPrompts?: readonly McpCapabilityOverride[];
+  /**
+   * Re-run the catalog sync on every reconcile, not only after the create.
+   * ⚠️ A sync is a WRITE that talks to the upstream server; leaving this off keeps a no-op deploy
+   *   from waking it. Turn it on for a server whose tool list changes with its own releases.
+   */
+  readonly resync?: boolean;
+}
+
+export interface McpServerAttributes {
+  readonly serverId: string;
+  /** The account the provider environment resolved when the entry was written. */
+  readonly accountId: string;
+  readonly name: string;
+  readonly hostname: string;
+  readonly authType: McpServerAuthType;
+  readonly description: string | undefined;
+  readonly isSharedOauthCallbackEnabled: boolean;
+  readonly secureWebGateway: boolean;
+  /** Catalog sync state as of the last read or write. It moves on its own. */
+  readonly status: McpServerStatus | undefined;
+  /** `required` means an administrator must still finish the upstream OAuth flow by hand. */
+  readonly authenticationStatus: McpServerAuthenticationStatus | undefined;
+  readonly lastSynced: string | undefined;
+  readonly createdAt: string | undefined;
+  /** `scrypt:<salt>:<digest>` of the credential last written, or `''`. ⛔ Never the value. */
+  readonly authCredentialsSeal: string;
+  /** `scrypt:<salt>:<digest>` of the client secret last written, or `''`. ⛔ Never the value. */
+  readonly clientSecretSeal: string;
+}
+
+const ID_SHAPE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+const idProblem = (serverId: unknown): string | undefined => {
+  if (typeof serverId !== 'string' || serverId.length === 0) return 'must be a non-empty string';
+  if (serverId !== serverId.trim()) return 'has leading or trailing whitespace';
+  if (!ID_SHAPE.test(serverId)) {
+    return 'must be 1-64 characters of letters, digits, dot, dash or underscore, starting with a letter or digit';
+  }
+  return undefined;
+};
+
+/**
+ * ⛔ THE ONE REFUSAL THAT PAYS FOR ITSELF: a bare host in `hostname`. The field's NAME invites it,
+ *   the API accepts it, and the portal then has no endpoint to call.
+ */
+const hostnameProblem = (hostname: unknown): string | undefined => {
+  if (typeof hostname !== 'string' || hostname.length === 0) return 'must be a non-empty string';
+  let url: URL;
+  try {
+    url = new URL(hostname);
+  } catch {
+    return `must be a full URL including the scheme and path, e.g. "https://${hostname}/mcp" — the field is named \`hostname\` but Cloudflare documents it as "URL of the upstream MCP endpoint"`;
+  }
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    return `must be an http(s) URL; "${url.protocol}" is not one the portal can fetch`;
+  }
+  if (url.hash !== '') return 'must not carry a fragment; the portal sends the URL as given';
+  return undefined;
+};
+
+/** Which credential props each auth type may carry. ⛔ Fail closed on a combination nobody meant. */
+const credentialProblem = (props: McpServerProps): string | undefined => {
+  const hasCredentials = props.authCredentials !== undefined;
+  const hasSecret = props.clientSecret !== undefined;
+  if (props.authType === 'bearer') {
+    if (!hasCredentials) return '`authType: "bearer"` needs `authCredentials: { fromEnv: … }`';
+    if (hasSecret) return '`clientSecret` belongs to a manual-mode `oauth` entry, not to `bearer`';
+    return undefined;
+  }
+  if (hasCredentials) {
+    return `\`authCredentials\` is the static credential for \`authType: "bearer"\`; this entry is "${props.authType}"`;
+  }
+  if (props.authType === 'unauthenticated' && hasSecret) {
+    return '`clientSecret` belongs to a manual-mode `oauth` entry, not to `unauthenticated`';
+  }
+  return undefined;
+};
+
+/** ⛔ Fail closed on a declaration the API would accept but nobody meant. */
+export const validateMcpServer = (props: McpServerProps): McpServerError | undefined => {
+  const id = idProblem(props.serverId);
+  if (id !== undefined) return new McpServerError({ message: `McpServer \`serverId\` ${id}.` });
+  const host = hostnameProblem(props.hostname);
+  if (host !== undefined) {
+    return new McpServerError({
+      message: `McpServer "${props.serverId}" \`hostname\` ${host}.`,
+    });
+  }
+  if (
+    props.authType !== 'oauth' &&
+    props.authType !== 'bearer' &&
+    props.authType !== 'unauthenticated'
+  ) {
+    return new McpServerError({
+      message: `McpServer "${props.serverId}" \`authType\` must be "oauth", "bearer" or "unauthenticated". It is create-only, so it has no default.`,
+    });
+  }
+  const credential = credentialProblem(props);
+  return credential === undefined
+    ? undefined
+    : new McpServerError({ message: `McpServer "${props.serverId}": ${credential}.` });
+};
+
+/**
+ * update or replace, from the declaration and what was last written.
+ *
+ * - Account changed → `replace`, create-first: ids are unique per ACCOUNT, so nothing collides.
+ * - `serverId` changed → `replace`, create-first: the new entry's id is free by definition.
+ * - `hostname` or `authType` changed → `replace`, and ⛔ `deleteFirst` when the id stays the
+ *   same, because the new generation must create the SAME id the old one still holds. Create-first
+ *   there would answer "already exists" — or, worse, a create path that "converged" on the live
+ *   entry would record a hostname it does not have.
+ * - Otherwise → no opinion; the engine compares props.
+ *
+ * ⚠️ A deleteFirst replace means the entry is briefly absent from the portal, and the Access
+ *   application that names `mcpServerId` keeps pointing at an id that exists again a moment later.
+ *   That is the only order the API allows for a create-only field on a client-supplied id.
+ */
+export const diffMcpServer = (
+  news: Input<McpServerProps>,
+  output: McpServerAttributes | undefined,
+  accountId: string,
+): Diff | undefined => {
+  if (output === undefined) return undefined;
+  if (output.accountId !== accountId) return { action: 'replace' };
+  const fields = news as {
+    readonly serverId?: unknown;
+    readonly hostname?: unknown;
+    readonly authType?: unknown;
+  };
+  const serverId = typeof fields.serverId === 'string' ? fields.serverId : undefined;
+  if (serverId !== undefined && serverId !== output.serverId) return { action: 'replace' };
+  const hostname = typeof fields.hostname === 'string' ? fields.hostname : undefined;
+  const authType = typeof fields.authType === 'string' ? fields.authType : undefined;
+  const createOnlyMoved =
+    (hostname !== undefined && hostname !== output.hostname) ||
+    (authType !== undefined && authType !== output.authType);
+  if (!createOnlyMoved) return undefined;
+  // ★ An unresolved `serverId` counts as unchanged, which picks the order that cannot collide.
+  return serverId === undefined || serverId === output.serverId
+    ? { action: 'replace', deleteFirst: true }
+    : { action: 'replace' };
+};

package/src/index.ts

@@ -11,6 +11,7 @@
  *     import { TalosCluster } from '@homeflare/alchemy/talos';
  *     import { ProxmoxAcl } from '@homeflare/alchemy/proxmox';
  *     import { LaunchdJob } from '@homeflare/alchemy/launchd';
+ *     import { ReleaseBinary } from '@homeflare/alchemy/release';
  *     import { CaddyConfig } from '@homeflare/alchemy/caddy';
  *
  * ★ WHY THESE EXIST AT ALL. When Alchemy has no resource for something, the alternative