@homeflare/alchemy 0.20.0 → 0.21.0

package/dist/cloudflare/mcp-server-form.d.ts

@@ -0,0 +1,116 @@
+/**
+ * `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;
+}
+/** ⛔ Fail closed on a declaration the API would accept but nobody meant. */
+export declare const validateMcpServer: (props: McpServerProps) => McpServerError | undefined;
+/**
+ * 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 declare const diffMcpServer: (news: Input<McpServerProps>, output: McpServerAttributes | undefined, accountId: string) => Diff | undefined;
+//# sourceMappingURL=mcp-server-form.d.ts.map

package/dist/cloudflare/mcp-server-form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server-form.d.ts","sourceRoot":"","sources":["../../src/cloudflare/mcp-server-form.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,6BAA6B,EAClC,cAAc,EACd,KAAK,eAAe,EACrB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,WAAW,cAAc;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,sDAAsD;IACtD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;;OASG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,gGAAgG;IAChG,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;OAEG;IACH,QAAQ,CAAC,4BAA4B,CAAC,EAAE,OAAO,CAAC;IAChD,yFAAyF;IACzF,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IACpC,oFAAoF;IACpF,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACzD,oCAAoC;IACpC,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC3D;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gFAAgF;IAChF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,4BAA4B,EAAE,OAAO,CAAC;IAC/C,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAAC;IAC7C,2FAA2F;IAC3F,QAAQ,CAAC,oBAAoB,EAAE,6BAA6B,GAAG,SAAS,CAAC;IACzE,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,2FAA2F;IAC3F,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,8FAA8F;IAC9F,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAkDD,4EAA4E;AAC5E,eAAO,MAAM,iBAAiB,UAAW,cAAc,KAAG,cAAc,GAAG,SAsB1E,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,aAAa,SAClB,KAAK,CAAC,cAAc,CAAC,UACnB,mBAAmB,GAAG,SAAS,aAC5B,MAAM,KAChB,IAAI,GAAG,SAoBT,CAAC"}

package/dist/index.d.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

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,CAAC"}

package/dist/launchd/file-converge.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The one path a declared file's bytes take onto a host, shared by every resource that owns ONE
+ * whole file: `Host.File` (text it was handed) and `Release.Binary` (bytes it downloaded and
+ * verified). Read, diff, converge and delete, as plain async functions over a HostRunner.
+ *
+ * ★ EXTRACTED FROM host-file-lifecycle.ts, NOT COPIED (2026-09-22). The ownership rules below — a
+ *   file this resource does not own is never overwritten, a move onto an occupied path stays
+ *   refused, a failed create is rolled back — were red-teamed on Host.File (docs/ownership.md). A
+ *   second resource that writes a whole file gets them by calling this, so a fix lands in both.
+ * ★ THE BYTES ARE ASKED FOR ONLY WHEN A WRITE IS DUE (`bytesFor`). Host.File has them already; a
+ *   binary has only a pinned digest until it downloads, and a host whose file already matches
+ *   must not cost a 120 MB download to prove it.
+ * ⛔ SYMLINKS AND DIRECTORIES ARE REFUSED, NOT REPLACED. rename(2) over a symlink replaces the LINK,
+ *   so a path that is a symlink (nix-darwin's /etc entries point into /nix/store) would be quietly
+ *   taken from the tool that owns it — which puts it back, or refuses its next activation. Remove
+ *   the path from its owner first, then declare it here.
+ */
+import type { Diff } from 'alchemy/Diff';
+import type { HostFileAttributes } from './host-file-form.ts';
+import { type HostRunner, type WriteOptions } from './runner.ts';
+/** What a whole file must be: where, which bytes (by digest), which mode and owner. */
+export type FileTarget = {
+    readonly path: string;
+    readonly sha256: string;
+    readonly mode: number;
+    readonly uid?: number;
+    readonly gid?: number;
+};
+/** A family's refusal: `<Type> <path>: <message>`, so a deploy log names the resource that said no. */
+export type Refuse = (path: string, message: string) => Error;
+/** Resolve a declared owner and group (names or ids) to ids through the runner. */
+export declare const resolveIds: (runner: HostRunner, declared: {
+    readonly owner?: string | number;
+    readonly group?: string | number;
+}, path: string, refuse: Refuse) => Promise<{
+    uid?: number;
+    gid?: number;
+}>;
+/** The file as it is now, or `undefined` when nothing is at the path. Non-files read with no digest. */
+export declare const readFileAttributes: (runner: HostRunner, path: string) => Promise<HostFileAttributes | undefined>;
+export declare const writeOptionsOf: (want: FileTarget) => WriteOptions;
+export declare const fileMatches: (live: HostFileAttributes, want: FileTarget) => boolean;
+/**
+ * ★ A PLAN THAT WILL WRITE ASKS THE RUNNER FIRST (`checkWrite`, when it has one): sudoRunner's
+ *   refusals — a setuid or group-writable root file, a directory under a prefix another user may
+ *   change — then fail the plan, before any resource is applied, instead of halfway through it.
+ */
+export declare const diffTarget: (runner: HostRunner, want: FileTarget, output: HostFileAttributes) => Promise<Diff>;
+export type Converge = {
+    readonly want: FileTarget;
+    /** The owner as declared (a name or an id), for the chown refusal's wording. */
+    readonly owner?: string | number | undefined;
+    /** The bytes to write, asked for only when a write is due; `before` is what is there now. */
+    readonly bytesFor: (before: HostFileAttributes | undefined) => Promise<Uint8Array>;
+    readonly refuse: Refuse;
+};
+/**
+ * Make the file at `want.path` match `want`, and return it as read back.
+ *
+ * `adopt` is whether adoption is on AND this apply is a create or an unfinished generation of our
+ * own (ownership/adopt.ts adoptsAtApply). It lets such a generation take over a file already at the
+ * path — the takeover the plan's probe would have allowed, had it run. ⛔ A move onto an occupied
+ *   path stays refused, both ways the engine drives one: an `update` across the move (`moved`,
+ *   below), and a fresh replace's new generation, which the caller never marks adoptable (its
+ *   `output` is undefined too, so this function cannot tell it from a create by itself).
+ */
+export declare const convergeFile: (runner: HostRunner, spec: Converge, output?: HostFileAttributes, adopt?: boolean) => Promise<HostFileAttributes>;
+/** Remove the file. Idempotent. ⛔ Refuses a path that has since become a symlink or directory. */
+export declare const removeWholeFile: (runner: HostRunner, output: HostFileAttributes, refuse: Refuse) => Promise<void>;
+//# sourceMappingURL=file-converge.d.ts.map

package/dist/launchd/file-converge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-converge.d.ts","sourceRoot":"","sources":["../../src/launchd/file-converge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAgB,MAAM,aAAa,CAAC;AAE/E,uFAAuF;AACvF,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,uGAAuG;AACvG,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,KAAK,CAAC;AAK9D,mFAAmF;AACnF,eAAO,MAAM,UAAU,WACb,UAAU,YACR;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,QAC1E,MAAM,UACJ,MAAM,KACb,OAAO,CAAC;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,CAYxC,CAAC;AAEF,wGAAwG;AACxG,eAAO,MAAM,kBAAkB,WACrB,UAAU,QACZ,MAAM,KACX,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAYxC,CAAC;AAEF,eAAO,MAAM,cAAc,SAAU,UAAU,KAAG,YAIhD,CAAC;AAEH,eAAO,MAAM,WAAW,SAAU,kBAAkB,QAAQ,UAAU,KAAG,OAItB,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,UAAU,WACb,UAAU,QACZ,UAAU,UACR,kBAAkB,KACzB,OAAO,CAAC,IAAI,CAkBd,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,gFAAgF;IAChF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAC7C,6FAA6F;IAC7F,QAAQ,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,kBAAkB,GAAG,SAAS,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IACnF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,WACf,UAAU,QACZ,QAAQ,WACL,kBAAkB,sBAE1B,OAAO,CAAC,kBAAkB,CA+E5B,CAAC;AAEF,kGAAkG;AAClG,eAAO,MAAM,eAAe,WAClB,UAAU,UACV,kBAAkB,UAClB,MAAM,KACb,OAAO,CAAC,IAAI,CAKd,CAAC"}

package/dist/launchd/file-identity.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Whether two paths name ONE file — the question a move must answer before it deletes its old
+ * path, and a plan before it answers `replace`.
+ *
+ * 🔴 MEASURED 2026-09-22 (release/binary-alias.test.ts, localRunner over a real temp directory,
+ *   through Alchemy's own Plan and Apply): a Release.Binary whose directory was respelled to
+ *   another path for the SAME file — through a symlinked parent (`/tmp` → `/private/tmp`, `/etc`
+ *   → `/private/etc`), or by case alone on case-insensitive APFS, macOS's default — planned a
+ *   `replace`. The new generation took the file already there as its own (same bytes, same mode:
+ *   file-converge.ts's resume rule), then Phase 2 deleted the old generation's path, which was that
+ *   same file. The deploy SUCCEEDED and the binary was gone. The `update` route lost it in one step:
+ *   convergeFile's move removed the old path after "writing" the new one. Host.File shares both.
+ * ★ IDENTITY, NOT SPELLING. Case-folding the strings would be wrong on a case-sensitive volume and
+ *   blind to a symlinked parent; device and inode from lstat are what the kernel itself compares.
+ * ⚠️ A HARD LINK also shares an inode. At the old path of a move it is therefore kept, not removed:
+ *   one stray link left behind, rather than the risk of deleting the file just verified.
+ */
+import type { FileStat, HostRunner } from './runner.ts';
+/**
+ * `true` when both entries exist and are one file; `false` when either is absent or they differ;
+ * `undefined` when the runner reported no identity, so nobody can tell (fakes, custom runners).
+ */
+export declare const sameEntry: (a: FileStat | undefined, b: FileStat | undefined) => boolean | undefined;
+/** Whether `a` and `b` are one file on this host right now. Equal strings always are. */
+export declare const oneFile: (runner: HostRunner, a: string, b: string) => Promise<boolean | undefined>;
+/**
+ * The last step of a move: `remove` the old path unless it is the file just verified at `path`.
+ * ⚠️ A runner that reports no identity cannot be asked beforehand, so `path` is checked after: a
+ *   file lost to a respelling then fails the deploy instead of reporting success.
+ */
+export declare const leaveOldPath: (runner: HostRunner, oldPath: string, path: string, remove: () => Promise<void>, refuse: (path: string, message: string) => Error) => Promise<void>;
+//# sourceMappingURL=file-identity.d.ts.map

package/dist/launchd/file-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-identity.d.ts","sourceRoot":"","sources":["../../src/launchd/file-identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,SAAS,MACjB,QAAQ,GAAG,SAAS,KACpB,QAAQ,GAAG,SAAS,KACtB,OAAO,GAAG,SAMZ,CAAC;AAEF,yFAAyF;AACzF,eAAO,MAAM,OAAO,WACV,UAAU,KACf,MAAM,KACN,MAAM,KACR,OAAO,CAAC,OAAO,GAAG,SAAS,CAI7B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,YAAY,WACf,UAAU,WACT,MAAM,QACT,MAAM,UACJ,MAAM,OAAO,CAAC,IAAI,CAAC,UACnB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,KAAK,KAC/C,OAAO,CAAC,IAAI,CAYd,CAAC"}

package/dist/launchd/host-file-form.d.ts

@@ -20,6 +20,8 @@ export interface HostFileAttributes {
     size: number;
 }
 export declare const DEFAULT_MODE = 420;
+/** A user or group as declared: a non-negative id, or a name the host could have. */
+export declare const identityProblems: (name: string, value: string | number | undefined) => string[];
 /**
  * An absolute, normalised path, or the reasons it is not. ★ Shared with sudo-allowlist.ts, so a
  *   path the sudo runner may touch as root obeys exactly the rule a declared file does.

package/dist/launchd/host-file-form.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host-file-form.d.ts","sourceRoot":"","sources":["../../src/launchd/host-file-form.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kGAAkG;IAClG,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,YAAY,MAAQ,CAAC;AAclC;;;GAGG;AACH,eAAO,MAAM,YAAY,SAAU,MAAM,KAAG,MAAM,EAgBjD,CAAC;AAEF,eAAO,MAAM,YAAY,UAAW,aAAa,KAAG,MAAM,EAQzD,CAAC"}
+{"version":3,"file":"host-file-form.d.ts","sourceRoot":"","sources":["../../src/launchd/host-file-form.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kGAAkG;IAClG,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,YAAY,MAAQ,CAAC;AAElC,qFAAqF;AACrF,eAAO,MAAM,gBAAgB,SAAU,MAAM,SAAS,MAAM,GAAG,MAAM,GAAG,SAAS,KAAG,MAAM,EAUzF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,YAAY,SAAU,MAAM,KAAG,MAAM,EAgBjD,CAAC;AAEF,eAAO,MAAM,YAAY,UAAW,aAAa,KAAG,MAAM,EAQzD,CAAC"}

package/dist/launchd/host-file-lifecycle.d.ts

@@ -2,41 +2,28 @@
  * HostFile's read / diff / reconcile / delete as plain async functions over a HostRunner, so the
  * lifecycle runs against fake-runner.ts in tests.
  *
- * ⛔ SYMLINKS AND DIRECTORIES ARE REFUSED, NOT REPLACED. rename(2) over a symlink replaces the LINK,
- *   so a path that is a symlink (nix-darwin's /etc entries point into /nix/store) would be quietly
- *   taken from the tool that owns it — which puts it back, or refuses its next activation. Remove
- *   the path from its owner first, then declare it here.
+ * ★ THE CONVERGENCE ITSELF IS file-converge.ts, shared with every resource that owns one whole file
+ *   (Release.Binary is the second). What stays here is what makes a HOST FILE: text content, its
+ *   validation (never a secret — host-file-form.ts), and the refusal wording `Host.File <path>: …`.
+ * ⛔ SYMLINKS AND DIRECTORIES ARE REFUSED, NOT REPLACED — see file-converge.ts for why.
  */
 import type { Diff } from 'alchemy/Diff';
+import { type FileTarget } from './file-converge.ts';
 import { type HostFileAttributes, type HostFileProps } from './host-file-form.ts';
-import { type HostRunner } from './runner.ts';
-type Desired = {
+import type { HostRunner } from './runner.ts';
+export { readFileAttributes } from './file-converge.ts';
+type Desired = FileTarget & {
     readonly bytes: Uint8Array;
-    readonly sha256: string;
-    readonly mode: number;
-    readonly uid?: number;
-    readonly gid?: number;
 };
 /** Validate, then resolve owner/group names to ids through the runner. */
 export declare const desiredFile: (runner: HostRunner, props: HostFileProps) => Promise<Desired>;
-/** The file as it is now, or `undefined` when nothing is at the path. Non-files read with no digest. */
-export declare const readFileAttributes: (runner: HostRunner, path: string) => Promise<HostFileAttributes | undefined>;
-/**
- * ★ A PLAN THAT WILL WRITE ASKS THE RUNNER FIRST (`checkWrite`, when it has one): sudoRunner's
- *   refusals — a setuid or group-writable root file, a directory under a prefix another user may
- *   change — then fail the plan, before any resource is applied, instead of halfway through it.
- */
+/** Declared digest, mode and owner against state and the live file — see diffTarget. */
 export declare const diffFile: (runner: HostRunner, news: HostFileProps, output: HostFileAttributes) => Promise<Diff>;
 /**
- * `adopt` is whether adoption is on AND this apply is a create or an unfinished generation of our
- * own (ownership/adopt.ts adoptsAtApply). It lets such a generation take over a file already at the
- * path — the takeover the plan's probe would have allowed, had it run. ⛔ A move onto an occupied
- *   path stays refused, both ways the engine drives one: an `update` across the move (`moved`,
- *   below), and a fresh replace's new generation, which the caller never marks adoptable (its
- *   `output` is undefined too, so this function cannot tell it from a create by itself).
+ * Write the declared text, unless the file already matches. `adopt` is adoptsAtApply's answer;
+ * what it may and may not take over is convergeFile's ⛔.
  */
 export declare const reconcileFile: (runner: HostRunner, props: HostFileProps, output?: HostFileAttributes, adopt?: boolean) => Promise<HostFileAttributes>;
 /** Remove the file. Idempotent. ⛔ Refuses a path that has since become a symlink or directory. */
 export declare const deleteFile: (runner: HostRunner, output: HostFileAttributes) => Promise<void>;
-export {};
 //# sourceMappingURL=host-file-lifecycle.d.ts.map

package/dist/launchd/host-file-lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host-file-lifecycle.d.ts","sourceRoot":"","sources":["../../src/launchd/host-file-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAEnB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,KAAK,UAAU,EAAmC,MAAM,aAAa,CAAC;AAE/E,KAAK,OAAO,GAAG;IACb,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAOF,0EAA0E;AAC1E,eAAO,MAAM,WAAW,WAAkB,UAAU,SAAS,aAAa,KAAG,OAAO,CAAC,OAAO,CAqB3F,CAAC;AAEF,wGAAwG;AACxG,eAAO,MAAM,kBAAkB,WACrB,UAAU,QACZ,MAAM,KACX,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAYxC,CAAC;AAcF;;;;GAIG;AACH,eAAO,MAAM,QAAQ,WACX,UAAU,QACZ,aAAa,UACX,kBAAkB,KACzB,OAAO,CAAC,IAAI,CAad,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,WAChB,UAAU,SACX,aAAa,WACX,kBAAkB,sBAE1B,OAAO,CAAC,kBAAkB,CA0D5B,CAAC;AAEF,kGAAkG;AAClG,eAAO,MAAM,UAAU,WAAkB,UAAU,UAAU,kBAAkB,KAAG,OAAO,CAAC,IAAI,CAK7F,CAAC"}
+{"version":3,"file":"host-file-lifecycle.d.ts","sourceRoot":"","sources":["../../src/launchd/host-file-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EACL,KAAK,UAAU,EAKhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAEnB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,KAAK,OAAO,GAAG,UAAU,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;CAAE,CAAC;AAI3D,0EAA0E;AAC1E,eAAO,MAAM,WAAW,WAAkB,UAAU,SAAS,aAAa,KAAG,OAAO,CAAC,OAAO,CAW3F,CAAC;AAEF,wFAAwF;AACxF,eAAO,MAAM,QAAQ,WACX,UAAU,QACZ,aAAa,UACX,kBAAkB,KACzB,OAAO,CAAC,IAAI,CAAgE,CAAC;AAEhF;;;GAGG;AACH,eAAO,MAAM,aAAa,WAChB,UAAU,SACX,aAAa,WACX,kBAAkB,sBAE1B,OAAO,CAAC,kBAAkB,CAI5B,CAAC;AAEF,kGAAkG;AAClG,eAAO,MAAM,UAAU,WAAY,UAAU,UAAU,kBAAkB,KAAG,OAAO,CAAC,IAAI,CAC/C,CAAC"}

package/dist/launchd/host-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host-file.d.ts","sourceRoot":"","sources":["../../src/launchd/host-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAK7C,OAAO,KAAK,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAE7E,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,YAAY,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAE7E,MAAM,WAAW,QAAS,SAAQ,QAAQ,CAAC,WAAW,EAAE,aAAa,EAAE,kBAAkB,CAAC;CAAG;AAE7F,eAAO,MAAM,QAAQ,2CAAkC,CAAC;AAExD,eAAO,MAAM,gBAAgB,2FAsC1B,CAAC"}
+{"version":3,"file":"host-file.d.ts","sourceRoot":"","sources":["../../src/launchd/host-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAM7C,OAAO,KAAK,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAE7E,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,YAAY,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAE7E,MAAM,WAAW,QAAS,SAAQ,QAAQ,CAAC,WAAW,EAAE,aAAa,EAAE,kBAAkB,CAAC;CAAG;AAE7F,eAAO,MAAM,QAAQ,2CAAkC,CAAC;AAExD,eAAO,MAAM,gBAAgB,2FA2C1B,CAAC"}