@homeflare/alchemy 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Timothy Schneider <tim@taslabs.net>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# @homeflare/alchemy
+
+Custom [Alchemy](https://alchemy.run) providers for gaps the vendor SDK leaves.
+
+```sh
+bun add @homeflare/alchemy alchemy cloudflare effect
+```
+
+★ **Why a custom provider at all.** When Alchemy has no property for something, the
+alternative is a runbook step a human runs once — and a plan can never show a missing
+runbook step. Covering the gap with a resource means the drift is visible in `plan` like
+everything else.
+
+## R2BucketLock
+
+An R2 bucket's lock rules, declared rather than applied by hand. A lock rule is a
+**retention floor**: while a rule covers an object, no API call, no lifecycle rule and no
+credential can delete it.
+
+```ts
+import { R2BucketLock } from '@homeflare/alchemy';
+import { providers } from '@homeflare/alchemy/providers';
+
+export class BackupLock extends R2BucketLock('backup-lock', {
+  bucketName: 'my-backups',
+  jurisdiction: 'default',
+  rules: [{ id: 'keep-30d', enabled: true, condition: { type: 'Age', maxAgeSeconds: 2_592_000 } }],
+}) {}
+```
+
+Add the provider layer to your stack:
+
+```ts
+import { providers } from '@homeflare/alchemy/providers';
+// …then provide `providers()` alongside Cloudflare.providers()
+```
+
+⚠️ **The rule set is REPLACE, not merge.** The API `PUT`s the whole set, so a rule omitted
+from `rules` is a rule deleted. That is the same shape as the Cloudflare API itself.
+
+⛔ **Deletion is refused by design.** Removing a lock is removing a retention floor, which
+is the one operation this resource exists to make hard. It retains on destroy.
+
+## Credentials
+
+`CLOUDFLARE_API_TOKEN` is read from the environment at call time, never at module scope.
+
+⛔ **Mint a short-lived, scoped token** — do not reuse a long-lived one, and never a Global
+API Key. An empty value fails closed with a message saying so, because an empty render is
+a denied grant rather than a missing file, and `Bearer ` + nothing 401s in a way that reads
+like a bad credential.
+
+## Peers
+
+`alchemy` >= 2.0.0-beta.77 · `cloudflare` >= 4.5.0 · `effect` >= 4.0.0-rc.112
+
+⚠️ Peers, not dependencies: Alchemy's resource registry and Effect's context both break if
+two copies load in one process.
+
+## License
+
+MIT © Timothy Schneider

package/dist/cloudflare/client.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The Cloudflare REST API as an Effect service, over `cloudflare-typescript`. Codex standard 5:
+ * the vendor's SDK, never a hand-rolled client — and never a hand-rolled `fetch` either.
+ *
+ * ⛔ THE SDK WAS ALREADY IN THE STORE AND DECLARED BY NOBODY. Measured 2026-09-15:
+ *   `node_modules/.pnpm/cloudflare@4.5.0` exists as a transitive dependency of `alchemy`, and
+ *   `pnpm ls cloudflare --depth 0` at the root and in every workspace package returns nothing.
+ *   `house/local/scripts/vendor-sdk-ratchet.ts` row R2 says exactly that — "not declared anywhere
+ *   in the workspace yet … the row adds the dependency once, then converts the TS callers" — so
+ *   this package is that row's first half, and the twenty ratcheted offences keep their rows.
+ *
+ * ⛔ AND IT IS PINNED EXACTLY, NOT `catalog:`. There is no catalog entry for `cloudflare`, and the
+ *   version that resolves today is the one alchemy pulls in. Pinning `4.5.0` means a future
+ *   alchemy bump moves alchemy's copy and not this package's contract — the alternative is a
+ *   provider whose request shape changes because an unrelated dependency was upgraded.
+ *
+ * ⚠️ `fetch` IS A SEAM, NOT A CONVENIENCE — the same argument `packages/litellm-client` makes. The
+ *   SDK hands its custom fetch the URL and init it built, so a test double conforming to
+ *   `Core.Fetch` exercises the real path assembly, the real body serialisation and the real header
+ *   set. A test that stubbed `client.r2.buckets.locks.update` would prove only that a stub was
+ *   called, which is precisely the class of check this estate keeps finding green over nothing.
+ */
+import Cloudflare from 'cloudflare';
+import * as Context from 'effect/Context';
+import * as Layer from 'effect/Layer';
+/** What the SDK accepts for `fetch`, restated so tests can name it without importing SDK internals. */
+export type ClientFetch = (url: string | URL | Request, init?: RequestInit) => Promise<Response>;
+declare const CloudflareApi_base: Context.ServiceClass<CloudflareApi, "homeflare/CloudflareApi", Cloudflare>;
+export declare class CloudflareApi extends CloudflareApi_base {
+}
+/**
+ * ⚠️ THE FAKE FETCH IS THE ONLY REASON THIS TAKES OPTIONS AT ALL. Everything else the SDK reads
+ *   from the environment the estate CLI already populates.
+ */
+export declare const makeClient: (options: {
+    apiToken: string;
+    fetch?: ClientFetch;
+}) => Cloudflare;
+/**
+ * ⛔ A LAYER'S ERROR CHANNEL MUST BE `never`, so a ConfigError becomes a defect carrying a sentence
+ *   rather than a type error pushed up into `Stack`. Same decision, same words, as `LiteLLMLive`.
+ */
+export declare const CloudflareApiLive: Layer.Layer<CloudflareApi, never, never>;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/cloudflare/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/cloudflare/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,UAAU,MAAM,YAAY,CAAC;AAEpC,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAE1C,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAGtC,uGAAuG;AACvG,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;;AAEjG,qBAAa,aAAc,SAAQ,kBAElC;CAAG;AAEJ;;;GAGG;AACH,eAAO,MAAM,UAAU,YAAa;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,WAAW,CAAA;CAAE,KAAG,UAI5E,CAAC;AAiBL;;;GAGG;AACH,eAAO,MAAM,iBAAiB,0CAU7B,CAAC"}

package/dist/cloudflare/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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.
+ */
+export type { R2LockRule } from './lock-rules.ts';
+export { R2BucketLock, type R2BucketLockProps } from './r2-bucket-lock.ts';
+export { providers } from './providers.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/cloudflare/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cloudflare/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC3E,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/cloudflare/index.js

@@ -0,0 +1,129 @@
+// src/cloudflare/r2-bucket-lock.ts
+import { Unowned } from "alchemy/AdoptPolicy";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import { NotFoundError } from "cloudflare";
+import * as Effect2 from "effect/Effect";
+
+// src/cloudflare/client.ts
+import Cloudflare from "cloudflare";
+import * as Config from "effect/Config";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+
+class CloudflareApi extends Context.Service()("homeflare/CloudflareApi") {
+}
+var makeClient = (options) => new Cloudflare({
+  apiToken: options.apiToken,
+  ...options.fetch === undefined ? {} : { fetch: options.fetch }
+});
+var MISSING_TOKEN = "CLOUDFLARE_API_TOKEN is not set. Mint a short-lived, scoped token and export it before " + "role named in estate.stack.ts; running `alchemy` directly skips that and there is no default.";
+var EMPTY_TOKEN = "CLOUDFLARE_API_TOKEN is set but EMPTY. That is a denied or missing OpenBao grant on the " + "stack’s role, not a rotated token — re-mint it rather than rotating anything at Cloudflare.";
+var CloudflareApiLive = Layer.effect(CloudflareApi, Effect.gen(function* () {
+  const token = yield* Config.redacted("CLOUDFLARE_API_TOKEN").pipe(Effect.catchTag("ConfigError", () => Effect.die(new Error(MISSING_TOKEN))));
+  const value2 = Redacted.value(token);
+  if (value2.length === 0)
+    return yield* Effect.die(new Error(EMPTY_TOKEN));
+  return makeClient({ apiToken: value2 });
+}));
+
+// src/cloudflare/lock-rules.ts
+var jurisdictionOf = (props) => props.jurisdiction ?? "default";
+function rulesEqual(a, b) {
+  if (a.length !== b.length)
+    return false;
+  return a.every((left, index) => {
+    const right = b[index];
+    if (right === undefined)
+      return false;
+    if (left.id !== right.id || left.enabled !== right.enabled)
+      return false;
+    if ((left.prefix ?? "") !== (right.prefix ?? ""))
+      return false;
+    const [lc, rc] = [left.condition, right.condition];
+    if (lc.type !== rc.type)
+      return false;
+    if (lc.type === "Age")
+      return rc.type === "Age" && lc.maxAgeSeconds === rc.maxAgeSeconds;
+    if (lc.type === "Date")
+      return rc.type === "Date" && lc.date === rc.date;
+    return true;
+  });
+}
+var toBody = (rules) => ({
+  rules: rules.map((rule) => ({ ...rule }))
+});
+
+// src/cloudflare/r2-bucket-lock.ts
+var R2BucketLock = Resource("Cloudflare.R2BucketLock", {
+  defaultRemovalPolicy: "retain"
+});
+var readLock = (client, props, written) => Effect2.gen(function* () {
+  const jurisdiction = jurisdictionOf(props);
+  const live = yield* Effect2.tryPromise({
+    try: () => client.r2.buckets.locks.get(props.bucketName, {
+      account_id: props.accountId,
+      jurisdiction
+    }),
+    catch: (cause) => cause
+  }).pipe(Effect2.catchIf((cause) => cause instanceof NotFoundError, () => Effect2.succeed(undefined)), Effect2.orDie);
+  if (live === undefined)
+    return;
+  const rules = live.rules ?? [];
+  if (rules.length === 0)
+    return;
+  const attributes = {
+    bucketName: props.bucketName,
+    jurisdiction,
+    rules
+  };
+  return written ? attributes : Unowned(attributes);
+});
+var reconcileLock = (client, news, output) => Effect2.gen(function* () {
+  const jurisdiction = jurisdictionOf(news);
+  if (output !== undefined && rulesEqual(output.rules, news.rules))
+    return output;
+  yield* Effect2.promise(() => client.r2.buckets.locks.update(news.bucketName, {
+    account_id: news.accountId,
+    jurisdiction,
+    ...toBody(news.rules)
+  }));
+  return { bucketName: news.bucketName, jurisdiction, rules: news.rules };
+});
+var deleteLock = (client, output, accountId) => Effect2.gen(function* () {
+  yield* Effect2.promise(() => client.r2.buckets.locks.update(output.bucketName, {
+    account_id: accountId,
+    jurisdiction: output.jurisdiction,
+    rules: []
+  }));
+});
+var R2BucketLockProvider = () => Provider.effect(R2BucketLock, Effect2.gen(function* () {
+  const client = yield* CloudflareApi;
+  return R2BucketLock.Provider.of({
+    list: () => Effect2.succeed([]),
+    nuke: { singleton: true },
+    read: Effect2.fn(function* ({ olds, output }) {
+      const props = olds ?? undefined;
+      if (props === undefined)
+        return;
+      return yield* readLock(client, props, output !== undefined);
+    }),
+    reconcile: Effect2.fn(({ news, output }) => reconcileLock(client, news, output)),
+    delete: Effect2.fn(({ olds, output }) => deleteLock(client, output, olds.accountId))
+  });
+}));
+// src/cloudflare/providers.ts
+import * as Provider2 from "alchemy/Provider";
+import * as Layer2 from "effect/Layer";
+class Providers extends Provider2.ProviderCollection()("HomeflareCloudflare") {
+}
+var providers = () => Layer2.effect(Providers, Provider2.collection([R2BucketLock])).pipe(Layer2.provide(R2BucketLockProvider()), Layer2.provideMerge(CloudflareApiLive));
+export {
+  R2BucketLock,
+  providers
+};
+
+//# debugId=DE23078825F2DFD564756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/cloudflare/index.js.map

@@ -0,0 +1,13 @@
+{
+  "version": 3,
+  "sources": ["../src/cloudflare/r2-bucket-lock.ts", "../src/cloudflare/client.ts", "../src/cloudflare/lock-rules.ts", "../src/cloudflare/providers.ts"],
+  "sourcesContent": [
+    "import { Unowned } from 'alchemy/AdoptPolicy';\nimport * as Provider from 'alchemy/Provider';\nimport { Resource, type ResourceClass } from 'alchemy/Resource';\n/**\n * `Cloudflare.R2BucketLock` — the lock rule set on one R2 bucket, declared rather than applied by\n * hand. A bucket lock is a RETENTION FLOOR: while a rule covers an object, no API call, no\n * lifecycle rule and no credential can delete it.\n *\n * 🔴 WHY THIS EXISTS AT ALL, AND WHAT IT REPLACES. a consuming stack shipped the retention floor as a\n *   documented `wrangler r2 bucket lock add …` step in the runbook, on the measured ground that\n *   `alchemy@2.0.0-beta.77` has no lock property anywhere in its R2 namespace. That measurement is\n *   still true and it was the wrong conclusion: a step a human runs once is a step an Alchemy plan\n *   can never show missing, so removing the floor by hand leaves that stack, its plan and\n *   every gate completely green. The operator's rule (2026-09-15) is to cover such a gap with a\n *   custom resource over the vendor's SDK, which is what this is.\n *\n * ⛔ THE SDK ALREADY HAD IT, AND THAT IS WORTH SAYING BECAUSE IT DECIDED THE SHAPE. Measured\n *   2026-09-15 in `cloudflare@4.5.0`, `resources/r2/buckets/locks.d.ts`:\n *\n *       update(bucketName: string, params: LockUpdateParams, options?): APIPromise<…>\n *       get(bucketName: string, params: LockGetParams, options?): APIPromise<LockGetResponse>\n *\n *   over `PUT`/`GET /accounts/{account_id}/r2/buckets/{bucket_name}/lock` with the jurisdiction\n *   carried as the `cf-r2-jurisdiction` header (`locks.mjs:17` and `:41`). So there is no raw\n *   `client.put` fallback here and no path string this package invented — the fallback the rule\n *   allows was not needed.\n *\n * ⚠️ THE RULE SET IS A REPLACE, NOT A MERGE. `PUT` takes the WHOLE list, exactly like R2's\n *   lifecycle rules — which is the trap a consuming stack records for\n *   `homeflare-git`. Declaring this resource on a bucket whose live rules nobody has read would\n *   drop them, so `read` fetches them first and `reconcile` refuses to write when they already\n *   match.\n */\nimport type Cloudflare from 'cloudflare';\nimport { NotFoundError } from 'cloudflare';\nimport * as Effect from 'effect/Effect';\nimport { CloudflareApi } from './client.ts';\nimport {\n  type Jurisdiction,\n  type R2LockRule,\n  jurisdictionOf,\n  rulesEqual,\n  toBody,\n} from './lock-rules.ts';\nimport type { Providers } from './providers.ts';\n\nexport interface R2BucketLockProps {\n  readonly accountId: string;\n  readonly bucketName: string;\n  /** ⚠️ Part of the bucket's IDENTITY, not a preference — a bucket in another jurisdiction is another bucket. */\n  readonly jurisdiction?: Jurisdiction;\n  /**\n   * ⛔ REQUIRED, AND ITS EMPTY VALUE IS THE DANGEROUS ONE. `rules: []` means NO FLOOR: it is what\n   *   `delete` sends to take a lock off deliberately. An optional property would let a declaration\n   *   that simply forgot it send `[]` and silently unlock the repository, reporting success — the\n   *   same reasoning `LiteLLM.McpServer.allowedTools` is required for.\n   */\n  readonly rules: readonly R2LockRule[];\n}\n\nexport type R2BucketLockAttributes = {\n  readonly bucketName: string;\n  readonly jurisdiction: Jurisdiction;\n  readonly rules: readonly R2LockRule[];\n};\n\nexport interface R2BucketLock extends Resource<\n  'Cloudflare.R2BucketLock',\n  R2BucketLockProps,\n  R2BucketLockAttributes,\n  never,\n  Providers\n> {}\n\n// ⚠️ EXPLICIT ANNOTATION, REQUIRED BY isolatedDeclarations. This file was internal to a\n//   monorepo before it was published; a published package emits its .d.ts from a separate\n//   tsc pass, so every exported symbol must state its type rather than infer it.\nexport const R2BucketLock: ResourceClass<R2BucketLock> = Resource<R2BucketLock>(\n  'Cloudflare.R2BucketLock',\n  {\n    /**\n     * ⛔ RETAIN, AND ON THIS RESOURCE IT IS NOT THE ESTATE'S HABIT BUT THE WHOLE POINT. A lock is a\n     *   safety floor: removing the declaration must not remove the floor, because the state it\n     *   protects is the only physical backup of the estate's one Postgres. `delete` below is\n     *   implemented — a provider that cannot delete cannot be tested or corrected — and it is\n     *   reachable only by an operator running the CLI directly, past a deploy wrapper.\n     */\n    defaultRemovalPolicy: 'retain',\n  },\n);\n\n/**\n * 🔴 A 404 HERE IS \"NOTHING TO ADOPT\", AND THE FIRST PLAN PROVED IT IS THE ORDINARY CASE.\n *   Measured 2026-09-15, an alchemy plan --detailed on a bucket that does not\n *   exist yet: `404 {\"success\":false,\"errors\":[{\"code\":10006,\"message\":\"The specified bucket does\n *   not exist.\"}]}` — raised from `read`, during PLANNING, before anything is created. Alchemy\n *   calls `read` for a resource with no prior state, so on every first deploy the lock is asked\n *   about a bucket the same plan is about to create. Letting that throw makes the resource\n *   impossible to plan; swallowing it with `catchAll` would also hide a 403 from a mis-scoped\n *   token, which is the failure this estate spends the most time on. So: 404 → absent, everything\n *   else propagates.\n *\n * ⛔ AN EMPTY LIVE RULE SET IS \"NO LOCK\", NOT \"A LOCK WITH NOTHING IN IT\", so it reads as absent\n *   and the resource CREATES. The API answers `{}` for a bucket that has never been locked and\n *   `{ rules: [] }` for one whose rules were removed; both mean the floor is gone.\n * ⚠️ `Unowned` UNTIL THIS STACK HAS WRITTEN IT. A lock someone applied by hand — which is exactly\n *   what the retired runbook step did — must not be silently rewritten by a mistyped declaration;\n *   the planner refuses until the resource is piped through `adopt(true)`, which is one line an\n *   operator reads in the diff. An adopted rule set that already MATCHES then costs no request at\n *   all, because `reconcile` below returns before writing.\n */\nexport const readLock = (\n  client: Cloudflare,\n  props: { accountId: string; bucketName: string; jurisdiction?: Jurisdiction },\n  written: boolean,\n): Effect.Effect<R2BucketLockAttributes | undefined> =>\n  Effect.gen(function* () {\n    const jurisdiction = jurisdictionOf(props);\n    const live = yield* Effect.tryPromise({\n      try: () =>\n        client.r2.buckets.locks.get(props.bucketName, {\n          account_id: props.accountId,\n          jurisdiction,\n        }),\n      catch: (cause) => cause,\n    }).pipe(\n      Effect.catchIf(\n        (cause) => cause instanceof NotFoundError,\n        () => Effect.succeed(undefined),\n      ),\n      Effect.orDie,\n    );\n    if (live === undefined) return undefined;\n    const rules = (live.rules ?? []) as readonly R2LockRule[];\n    if (rules.length === 0) return undefined;\n    const attributes: R2BucketLockAttributes = {\n      bucketName: props.bucketName,\n      jurisdiction,\n      rules,\n    };\n    return written ? attributes : Unowned(attributes);\n  });\n\n/**\n * ⛔ A NO-OP MAKES NO REQUEST, AND ON A LOCK THAT MATTERS MORE THAN TIDINESS. `PUT` replaces the\n *   rule set; re-sending an identical one on every deploy is a write against the only thing\n *   standing between this repository and a delete, for no change. `output` is what the last deploy\n *   persisted (or what `read` just adopted), so the comparison costs nothing either.\n */\nexport const reconcileLock = (\n  client: Cloudflare,\n  news: R2BucketLockProps,\n  output: R2BucketLockAttributes | undefined,\n): Effect.Effect<R2BucketLockAttributes> =>\n  Effect.gen(function* () {\n    const jurisdiction = jurisdictionOf(news);\n    if (output !== undefined && rulesEqual(output.rules, news.rules)) return output;\n    yield* Effect.promise(() =>\n      client.r2.buckets.locks.update(news.bucketName, {\n        account_id: news.accountId,\n        jurisdiction,\n        ...toBody(news.rules),\n      }),\n    );\n    return { bucketName: news.bucketName, jurisdiction, rules: news.rules };\n  });\n\n/**\n * ⛔ DELETING THIS RESOURCE MEANS PUTTING AN EMPTY RULE SET, WHICH IS UNLOCKING THE BUCKET. It is\n *   implemented because the retirement path is real — R2 refuses to empty a bucket while any lock\n *   rule is configured, so retiring the repository has to start here — and it is behind\n *   `defaultRemovalPolicy: 'retain'` and the estate CLI's refusal of `destroy` precisely because\n *   no ordinary deploy should ever reach it.\n */\nexport const deleteLock = (\n  client: Cloudflare,\n  output: R2BucketLockAttributes,\n  accountId: string,\n): Effect.Effect<void> =>\n  Effect.gen(function* () {\n    yield* Effect.promise(() =>\n      client.r2.buckets.locks.update(output.bucketName, {\n        account_id: accountId,\n        jurisdiction: output.jurisdiction,\n        rules: [],\n      }),\n    );\n  });\n\nexport const R2BucketLockProvider = () =>\n  Provider.effect(\n    R2BucketLock,\n    Effect.gen(function* () {\n      const client = yield* CloudflareApi;\n      return R2BucketLock.Provider.of({\n        /**\n         * ⛔ EMPTY, AND ALCHEMY'S OWN CONTRACT ASKS FOR EXACTLY THAT. `ProviderService.list`:\n         *   \"Resources with no native enumeration API (… sub-resources keyed entirely by a parent)\n         *   should return an empty array rather than throwing.\" There is no list-locks endpoint —\n         *   a lock is reachable only through the bucket that owns it — so enumerating would mean\n         *   listing every bucket in the account and GETting each one's lock.\n         * ⛔⛔ AND `nuke.singleton` IS WHY THAT IS NOT MERELY UNAVAILABLE BUT UNWANTED. `list`\n         *   feeds `alchemy unsafe nuke`, which lists and then deletes; `delete` here is an UNLOCK.\n         *   A working enumeration would hand one command the ability to strip the retention floor\n         *   off every bucket in the account — the precise event a floor exists to make impossible.\n         *   `singleton` is the documented word for it: always-present configuration whose delete\n         *   resets rather than removes.\n         */\n        list: () => Effect.succeed([]),\n        nuke: { singleton: true },\n        read: Effect.fn(function* ({ olds, output }) {\n          const props = olds ?? undefined;\n          if (props === undefined) return undefined;\n          return yield* readLock(client, props, output !== undefined);\n        }),\n        reconcile: Effect.fn(({ news, output }) => reconcileLock(client, news, output)),\n        delete: Effect.fn(({ olds, output }) => deleteLock(client, output, olds.accountId)),\n      });\n    }),\n  );\n",
+    "/**\n * The Cloudflare REST API as an Effect service, over `cloudflare-typescript`. Codex standard 5:\n * the vendor's SDK, never a hand-rolled client — and never a hand-rolled `fetch` either.\n *\n * ⛔ THE SDK WAS ALREADY IN THE STORE AND DECLARED BY NOBODY. Measured 2026-09-15:\n *   `node_modules/.pnpm/cloudflare@4.5.0` exists as a transitive dependency of `alchemy`, and\n *   `pnpm ls cloudflare --depth 0` at the root and in every workspace package returns nothing.\n *   `house/local/scripts/vendor-sdk-ratchet.ts` row R2 says exactly that — \"not declared anywhere\n *   in the workspace yet … the row adds the dependency once, then converts the TS callers\" — so\n *   this package is that row's first half, and the twenty ratcheted offences keep their rows.\n *\n * ⛔ AND IT IS PINNED EXACTLY, NOT `catalog:`. There is no catalog entry for `cloudflare`, and the\n *   version that resolves today is the one alchemy pulls in. Pinning `4.5.0` means a future\n *   alchemy bump moves alchemy's copy and not this package's contract — the alternative is a\n *   provider whose request shape changes because an unrelated dependency was upgraded.\n *\n * ⚠️ `fetch` IS A SEAM, NOT A CONVENIENCE — the same argument `packages/litellm-client` makes. The\n *   SDK hands its custom fetch the URL and init it built, so a test double conforming to\n *   `Core.Fetch` exercises the real path assembly, the real body serialisation and the real header\n *   set. A test that stubbed `client.r2.buckets.locks.update` would prove only that a stub was\n *   called, which is precisely the class of check this estate keeps finding green over nothing.\n */\nimport Cloudflare from 'cloudflare';\nimport * as Config from 'effect/Config';\nimport * as Context from 'effect/Context';\nimport * as Effect from 'effect/Effect';\nimport * as Layer from 'effect/Layer';\nimport * as Redacted from 'effect/Redacted';\n\n/** What the SDK accepts for `fetch`, restated so tests can name it without importing SDK internals. */\nexport type ClientFetch = (url: string | URL | Request, init?: RequestInit) => Promise<Response>;\n\nexport class CloudflareApi extends Context.Service<CloudflareApi, Cloudflare>()(\n  'homeflare/CloudflareApi',\n) {}\n\n/**\n * ⚠️ THE FAKE FETCH IS THE ONLY REASON THIS TAKES OPTIONS AT ALL. Everything else the SDK reads\n *   from the environment the estate CLI already populates.\n */\nexport const makeClient = (options: { apiToken: string; fetch?: ClientFetch }): Cloudflare =>\n  new Cloudflare({\n    apiToken: options.apiToken,\n    ...(options.fetch === undefined ? {} : { fetch: options.fetch }),\n  });\n\n/**\n * ⛔ FAIL CLOSED ON THE VALUE, NEVER ON THE VARIABLE EXISTING. AGENTS.md \"the four that cost the\n *   most\" §4: a denied OpenBao path renders the template EMPTY rather than erroring, and every\n *   Cloudflare call then answers 403 exactly like a revoked token — which sends the operator to\n *   Cloudflare to rotate a credential that was fine. Your deploy wrapper should write\n *   CLOUDFLARE_API_TOKEN from the stack's declared role, short-lived and scoped.\n */\nconst MISSING_TOKEN =\n  'CLOUDFLARE_API_TOKEN is not set. Mint a short-lived, scoped token and export it before ' +\n  'role named in estate.stack.ts; running `alchemy` directly skips that and there is no default.';\n\nconst EMPTY_TOKEN =\n  'CLOUDFLARE_API_TOKEN is set but EMPTY. That is a denied or missing OpenBao grant on the ' +\n  'stack’s role, not a rotated token — re-mint it rather than rotating anything at Cloudflare.';\n\n/**\n * ⛔ A LAYER'S ERROR CHANNEL MUST BE `never`, so a ConfigError becomes a defect carrying a sentence\n *   rather than a type error pushed up into `Stack`. Same decision, same words, as `LiteLLMLive`.\n */\nexport const CloudflareApiLive = Layer.effect(\n  CloudflareApi,\n  Effect.gen(function* () {\n    const token = yield* Config.redacted('CLOUDFLARE_API_TOKEN').pipe(\n      Effect.catchTag('ConfigError', () => Effect.die(new Error(MISSING_TOKEN))),\n    );\n    const value = Redacted.value(token);\n    if (value.length === 0) return yield* Effect.die(new Error(EMPTY_TOKEN));\n    return makeClient({ apiToken: value });\n  }),\n);\n",
+    "/**\n * The vocabulary of an R2 lock rule, and the comparison that decides whether to write one.\n *\n * ★ ITS OWN MODULE FOR THE REASON `house/litellm/src/equal.ts` IS ONE: the comparison is the\n *   riskiest function in the provider and it deserves to be readable and testable without the\n *   lifecycle around it. An equality that returned true for everything would make every reconcile\n *   a no-op and the resource would silently never write anything — which looks exactly like a\n *   converged stack.\n */\n/** Jurisdictions the API accepts, as the SDK declares them. */\nexport type Jurisdiction = 'default' | 'eu' | 'fedramp';\n\n/**\n * One lock rule. ⚠️ `prefix` OMITTED MEANS THE WHOLE BUCKET — the SDK documents an empty prefix as\n * the way to scope a rule to every object, and omitting the key is how that is spelled on the wire.\n */\nexport type R2LockRule = {\n  readonly id: string;\n  readonly enabled: boolean;\n  readonly prefix?: string;\n  readonly condition:\n    | { readonly type: 'Age'; readonly maxAgeSeconds: number }\n    | { readonly type: 'Date'; readonly date: string }\n    | { readonly type: 'Indefinite' };\n};\n\n/** ⚠️ `undefined` and `'default'` are the same jurisdiction; normalise so a diff never sees both. */\nexport const jurisdictionOf = (props: { readonly jurisdiction?: Jurisdiction }): Jurisdiction =>\n  props.jurisdiction ?? 'default';\n\n/**\n * ⛔ FIELD BY FIELD, IN ORDER, AND NOT `JSON.stringify` OF EITHER SIDE. The API returns rules in\n *   its own key order and omits `prefix` where this repo may spell it `''`; a stringify compare\n *   would report drift on every plan and PUT an identical body each deploy. Order across the list\n *   IS compared, because the rule set is a replace and the list is what gets sent.\n */\nexport function rulesEqual(a: readonly R2LockRule[], b: readonly R2LockRule[]): boolean {\n  if (a.length !== b.length) return false;\n  return a.every((left, index) => {\n    const right = b[index];\n    if (right === undefined) return false;\n    if (left.id !== right.id || left.enabled !== right.enabled) return false;\n    if ((left.prefix ?? '') !== (right.prefix ?? '')) return false;\n    const [lc, rc] = [left.condition, right.condition];\n    if (lc.type !== rc.type) return false;\n    if (lc.type === 'Age') return rc.type === 'Age' && lc.maxAgeSeconds === rc.maxAgeSeconds;\n    if (lc.type === 'Date') return rc.type === 'Date' && lc.date === rc.date;\n    return true;\n  });\n}\n\n/**\n * The body the SDK sends. Split out so the test can assert the wire shape against one function.\n *\n * ⚠️ IT TAKES THE RULES, NOT THE PROPS, so this module names nothing from the resource — the\n *   comparison and the vocabulary stay readable without the lifecycle around them.\n */\nexport const toBody = (rules: readonly R2LockRule[]): { rules: R2LockRule[] } => ({\n  rules: rules.map((rule) => ({ ...rule })),\n});\n",
+    "/**\n * The HomeFlare Cloudflare provider collection, in the shape `LiteLLM.providers()` has.\n *\n * ★ ONE LAYER, BUILT ONCE, so the single `Config.redacted('CLOUDFLARE_API_TOKEN')` read is shared\n *   by every resource in the stack rather than repeated per resource.\n *\n * ⚠️ THIS IS NOT `alchemy/Cloudflare`'s COLLECTION AND DOES NOT REPLACE IT. A stack that declares\n *   both a `Cloudflare.R2.Bucket` and this lock merges the two:\n *   `Layer.mergeAll(Cloudflare.providers(), HomeflareCloudflare.providers())` — the shape\n *   a consuming stack names for one talking to more than one account.\n */\nimport * as Provider from 'alchemy/Provider';\nimport * as Layer from 'effect/Layer';\nimport { CloudflareApiLive } from './client.ts';\nimport { R2BucketLock, R2BucketLockProvider } from './r2-bucket-lock.ts';\n\nexport class Providers extends Provider.ProviderCollection<Providers>()('HomeflareCloudflare') {}\n\nexport const providers = () =>\n  Layer.effect(Providers, Provider.collection([R2BucketLock])).pipe(\n    Layer.provide(R2BucketLockProvider()),\n    Layer.provideMerge(CloudflareApiLive),\n  );\n"
+  ],
+  "mappings": "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",
+  "debugId": "DE23078825F2DFD564756E2164756E21",
+  "names": []
+}

package/dist/cloudflare/lock-rules.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The vocabulary of an R2 lock rule, and the comparison that decides whether to write one.
+ *
+ * ★ ITS OWN MODULE FOR THE REASON `house/litellm/src/equal.ts` IS ONE: the comparison is the
+ *   riskiest function in the provider and it deserves to be readable and testable without the
+ *   lifecycle around it. An equality that returned true for everything would make every reconcile
+ *   a no-op and the resource would silently never write anything — which looks exactly like a
+ *   converged stack.
+ */
+/** Jurisdictions the API accepts, as the SDK declares them. */
+export type Jurisdiction = 'default' | 'eu' | 'fedramp';
+/**
+ * One lock rule. ⚠️ `prefix` OMITTED MEANS THE WHOLE BUCKET — the SDK documents an empty prefix as
+ * the way to scope a rule to every object, and omitting the key is how that is spelled on the wire.
+ */
+export type R2LockRule = {
+    readonly id: string;
+    readonly enabled: boolean;
+    readonly prefix?: string;
+    readonly condition: {
+        readonly type: 'Age';
+        readonly maxAgeSeconds: number;
+    } | {
+        readonly type: 'Date';
+        readonly date: string;
+    } | {
+        readonly type: 'Indefinite';
+    };
+};
+/** ⚠️ `undefined` and `'default'` are the same jurisdiction; normalise so a diff never sees both. */
+export declare const jurisdictionOf: (props: {
+    readonly jurisdiction?: Jurisdiction;
+}) => Jurisdiction;
+/**
+ * ⛔ FIELD BY FIELD, IN ORDER, AND NOT `JSON.stringify` OF EITHER SIDE. The API returns rules in
+ *   its own key order and omits `prefix` where this repo may spell it `''`; a stringify compare
+ *   would report drift on every plan and PUT an identical body each deploy. Order across the list
+ *   IS compared, because the rule set is a replace and the list is what gets sent.
+ */
+export declare function rulesEqual(a: readonly R2LockRule[], b: readonly R2LockRule[]): boolean;
+/**
+ * The body the SDK sends. Split out so the test can assert the wire shape against one function.
+ *
+ * ⚠️ IT TAKES THE RULES, NOT THE PROPS, so this module names nothing from the resource — the
+ *   comparison and the vocabulary stay readable without the lifecycle around them.
+ */
+export declare const toBody: (rules: readonly R2LockRule[]) => {
+    rules: R2LockRule[];
+};
+//# sourceMappingURL=lock-rules.d.ts.map

package/dist/cloudflare/lock-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock-rules.d.ts","sourceRoot":"","sources":["../../src/cloudflare/lock-rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,+DAA+D;AAC/D,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,IAAI,GAAG,SAAS,CAAC;AAExD;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EACd;QAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;QAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;KAAE,GACxD;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAChD;QAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;KAAE,CAAC;CACrC,CAAC;AAEF,qGAAqG;AACrG,eAAO,MAAM,cAAc,UAAW;IAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAA;CAAE,KAAG,YAChD,CAAC;AAElC;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,SAAS,UAAU,EAAE,EAAE,CAAC,EAAE,SAAS,UAAU,EAAE,GAAG,OAAO,CAatF;AAED;;;;;GAKG;AACH,eAAO,MAAM,MAAM,UAAW,SAAS,UAAU,EAAE,KAAG;IAAE,KAAK,EAAE,UAAU,EAAE,CAAA;CAEzE,CAAC"}

package/dist/cloudflare/providers.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The HomeFlare Cloudflare provider collection, in the shape `LiteLLM.providers()` has.
+ *
+ * ★ ONE LAYER, BUILT ONCE, so the single `Config.redacted('CLOUDFLARE_API_TOKEN')` read is shared
+ *   by every resource in the stack rather than repeated per resource.
+ *
+ * ⚠️ THIS IS NOT `alchemy/Cloudflare`'s COLLECTION AND DOES NOT REPLACE IT. A stack that declares
+ *   both a `Cloudflare.R2.Bucket` and this lock merges the two:
+ *   `Layer.mergeAll(Cloudflare.providers(), HomeflareCloudflare.providers())` — the shape
+ *   a consuming stack names for one talking to more than one account.
+ */
+import * as Provider from 'alchemy/Provider';
+import * as Layer from 'effect/Layer';
+declare const Providers_base: Provider.ProviderCollection<Providers, "HomeflareCloudflare">;
+export declare class Providers extends Providers_base {
+}
+export declare const providers: () => Layer.Layer<import("./client.ts").CloudflareApi | Providers, never, never>;
+export {};
+//# sourceMappingURL=providers.d.ts.map

package/dist/cloudflare/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../src/cloudflare/providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;;AAItC,qBAAa,SAAU,SAAQ,cAA+D;CAAG;AAEjG,eAAO,MAAM,SAAS,kFAInB,CAAC"}

package/dist/cloudflare/r2-bucket-lock.d.ts

@@ -0,0 +1,100 @@
+import * as Provider from 'alchemy/Provider';
+import { Resource, type ResourceClass } from 'alchemy/Resource';
+/**
+ * `Cloudflare.R2BucketLock` — the lock rule set on one R2 bucket, declared rather than applied by
+ * hand. A bucket lock is a RETENTION FLOOR: while a rule covers an object, no API call, no
+ * lifecycle rule and no credential can delete it.
+ *
+ * 🔴 WHY THIS EXISTS AT ALL, AND WHAT IT REPLACES. a consuming stack shipped the retention floor as a
+ *   documented `wrangler r2 bucket lock add …` step in the runbook, on the measured ground that
+ *   `alchemy@2.0.0-beta.77` has no lock property anywhere in its R2 namespace. That measurement is
+ *   still true and it was the wrong conclusion: a step a human runs once is a step an Alchemy plan
+ *   can never show missing, so removing the floor by hand leaves that stack, its plan and
+ *   every gate completely green. The operator's rule (2026-09-15) is to cover such a gap with a
+ *   custom resource over the vendor's SDK, which is what this is.
+ *
+ * ⛔ THE SDK ALREADY HAD IT, AND THAT IS WORTH SAYING BECAUSE IT DECIDED THE SHAPE. Measured
+ *   2026-09-15 in `cloudflare@4.5.0`, `resources/r2/buckets/locks.d.ts`:
+ *
+ *       update(bucketName: string, params: LockUpdateParams, options?): APIPromise<…>
+ *       get(bucketName: string, params: LockGetParams, options?): APIPromise<LockGetResponse>
+ *
+ *   over `PUT`/`GET /accounts/{account_id}/r2/buckets/{bucket_name}/lock` with the jurisdiction
+ *   carried as the `cf-r2-jurisdiction` header (`locks.mjs:17` and `:41`). So there is no raw
+ *   `client.put` fallback here and no path string this package invented — the fallback the rule
+ *   allows was not needed.
+ *
+ * ⚠️ THE RULE SET IS A REPLACE, NOT A MERGE. `PUT` takes the WHOLE list, exactly like R2's
+ *   lifecycle rules — which is the trap a consuming stack records for
+ *   `homeflare-git`. Declaring this resource on a bucket whose live rules nobody has read would
+ *   drop them, so `read` fetches them first and `reconcile` refuses to write when they already
+ *   match.
+ */
+import type Cloudflare from 'cloudflare';
+import * as Effect from 'effect/Effect';
+import { CloudflareApi } from './client.ts';
+import { type Jurisdiction, type R2LockRule } from './lock-rules.ts';
+import type { Providers } from './providers.ts';
+export interface R2BucketLockProps {
+    readonly accountId: string;
+    readonly bucketName: string;
+    /** ⚠️ Part of the bucket's IDENTITY, not a preference — a bucket in another jurisdiction is another bucket. */
+    readonly jurisdiction?: Jurisdiction;
+    /**
+     * ⛔ REQUIRED, AND ITS EMPTY VALUE IS THE DANGEROUS ONE. `rules: []` means NO FLOOR: it is what
+     *   `delete` sends to take a lock off deliberately. An optional property would let a declaration
+     *   that simply forgot it send `[]` and silently unlock the repository, reporting success — the
+     *   same reasoning `LiteLLM.McpServer.allowedTools` is required for.
+     */
+    readonly rules: readonly R2LockRule[];
+}
+export type R2BucketLockAttributes = {
+    readonly bucketName: string;
+    readonly jurisdiction: Jurisdiction;
+    readonly rules: readonly R2LockRule[];
+};
+export interface R2BucketLock extends Resource<'Cloudflare.R2BucketLock', R2BucketLockProps, R2BucketLockAttributes, never, Providers> {
+}
+export declare const R2BucketLock: ResourceClass<R2BucketLock>;
+/**
+ * 🔴 A 404 HERE IS "NOTHING TO ADOPT", AND THE FIRST PLAN PROVED IT IS THE ORDINARY CASE.
+ *   Measured 2026-09-15, an alchemy plan --detailed on a bucket that does not
+ *   exist yet: `404 {"success":false,"errors":[{"code":10006,"message":"The specified bucket does
+ *   not exist."}]}` — raised from `read`, during PLANNING, before anything is created. Alchemy
+ *   calls `read` for a resource with no prior state, so on every first deploy the lock is asked
+ *   about a bucket the same plan is about to create. Letting that throw makes the resource
+ *   impossible to plan; swallowing it with `catchAll` would also hide a 403 from a mis-scoped
+ *   token, which is the failure this estate spends the most time on. So: 404 → absent, everything
+ *   else propagates.
+ *
+ * ⛔ AN EMPTY LIVE RULE SET IS "NO LOCK", NOT "A LOCK WITH NOTHING IN IT", so it reads as absent
+ *   and the resource CREATES. The API answers `{}` for a bucket that has never been locked and
+ *   `{ rules: [] }` for one whose rules were removed; both mean the floor is gone.
+ * ⚠️ `Unowned` UNTIL THIS STACK HAS WRITTEN IT. A lock someone applied by hand — which is exactly
+ *   what the retired runbook step did — must not be silently rewritten by a mistyped declaration;
+ *   the planner refuses until the resource is piped through `adopt(true)`, which is one line an
+ *   operator reads in the diff. An adopted rule set that already MATCHES then costs no request at
+ *   all, because `reconcile` below returns before writing.
+ */
+export declare const readLock: (client: Cloudflare, props: {
+    accountId: string;
+    bucketName: string;
+    jurisdiction?: Jurisdiction;
+}, written: boolean) => Effect.Effect<R2BucketLockAttributes | undefined>;
+/**
+ * ⛔ A NO-OP MAKES NO REQUEST, AND ON A LOCK THAT MATTERS MORE THAN TIDINESS. `PUT` replaces the
+ *   rule set; re-sending an identical one on every deploy is a write against the only thing
+ *   standing between this repository and a delete, for no change. `output` is what the last deploy
+ *   persisted (or what `read` just adopted), so the comparison costs nothing either.
+ */
+export declare const reconcileLock: (client: Cloudflare, news: R2BucketLockProps, output: R2BucketLockAttributes | undefined) => Effect.Effect<R2BucketLockAttributes>;
+/**
+ * ⛔ DELETING THIS RESOURCE MEANS PUTTING AN EMPTY RULE SET, WHICH IS UNLOCKING THE BUCKET. It is
+ *   implemented because the retirement path is real — R2 refuses to empty a bucket while any lock
+ *   rule is configured, so retiring the repository has to start here — and it is behind
+ *   `defaultRemovalPolicy: 'retain'` and the estate CLI's refusal of `destroy` precisely because
+ *   no ordinary deploy should ever reach it.
+ */
+export declare const deleteLock: (client: Cloudflare, output: R2BucketLockAttributes, accountId: string) => Effect.Effect<void>;
+export declare const R2BucketLockProvider: () => import("effect/Layer").Layer<Provider.Provider<R2BucketLock>, never, CloudflareApi>;
+//# sourceMappingURL=r2-bucket-lock.d.ts.map

package/dist/cloudflare/r2-bucket-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"r2-bucket-lock.d.ts","sourceRoot":"","sources":["../../src/cloudflare/r2-bucket-lock.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAChE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,KAAK,UAAU,MAAM,YAAY,CAAC;AAEzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,UAAU,EAIhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,+GAA+G;IAC/G,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;CACvC;AAED,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;CACvC,CAAC;AAEF,MAAM,WAAW,YAAa,SAAQ,QAAQ,CAC5C,yBAAyB,EACzB,iBAAiB,EACjB,sBAAsB,EACtB,KAAK,EACL,SAAS,CACV;CAAG;AAKJ,eAAO,MAAM,YAAY,EAAE,aAAa,CAAC,YAAY,CAYpD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,QAAQ,WACX,UAAU,SACX;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,YAAY,CAAA;CAAE,WACpE,OAAO,KACf,MAAM,CAAC,MAAM,CAAC,sBAAsB,GAAG,SAAS,CA0B/C,CAAC;AAEL;;;;;GAKG;AACH,eAAO,MAAM,aAAa,WAChB,UAAU,QACZ,iBAAiB,UACf,sBAAsB,GAAG,SAAS,KACzC,MAAM,CAAC,MAAM,CAAC,sBAAsB,CAYnC,CAAC;AAEL;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,WACb,UAAU,UACV,sBAAsB,aACnB,MAAM,KAChB,MAAM,CAAC,MAAM,CAAC,IAAI,CASjB,CAAC;AAEL,eAAO,MAAM,oBAAoB,2FA8B9B,CAAC"}

package/dist/forgejo/branch-protection-form.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Create/PATCH bodies for `Forgejo.BranchProtection` — extracted for the 250-line cap.
+ *
+ * ★ READ OFF `house/mcp-servers/docs/api/upstream/forgejo.json` — create posts
+ *   `CreateBranchProtectionOption`; update sends `EditBranchProtectionOption` fields only.
+ */
+import type { BranchProtectionProps } from './branch-protection.ts';
+export declare const branchProtectionForm: (props: BranchProtectionProps) => {
+    apply_to_admins?: boolean;
+    dismiss_stale_approvals?: boolean;
+    enable_push?: boolean;
+    enable_status_check?: boolean;
+    ignore_stale_approvals?: boolean;
+    require_signed_commits?: boolean;
+    required_approvals?: number;
+    status_check_contexts?: string[];
+    rule_name: string;
+};
+//# sourceMappingURL=branch-protection-form.d.ts.map

package/dist/forgejo/branch-protection-form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-protection-form.d.ts","sourceRoot":"","sources":["../../src/forgejo/branch-protection-form.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAEpE,eAAO,MAAM,oBAAoB,UAAW,qBAAqB;;;;;;;;;;CAoB/D,CAAC"}

package/dist/forgejo/branch-protection.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `Forgejo.BranchProtection` — one rule at `/repos/{owner}/{repo}/branch_protections/{name}`.
+ *
+ * ★ READ OFF `house/mcp-servers/docs/api/upstream/forgejo.json`: create is POST collection;
+ *   read/update/delete use the branch/rule name in the path segment `{name}`. Response carries
+ *   `rule_name` (preferred) and deprecated `branch_name`.
+ *
+ * ⛔ `defaultRemovalPolicy: 'retain'` — dropping a protection rule from the stack must not silently
+ *   unprotect a branch; opt into `.pipe(RemovalPolicy.destroy())` to DELETE.
+ *
+ * ⛔ TOKEN NEEDS `write:repository` TO CREATE OR PATCH — get needs `read:repository`.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import { type ForgejoRequirements } from './resource.ts';
+export interface BranchProtectionProps {
+    owner: string;
+    repo: string;
+    /** Branch or rule name — path key and `rule_name` on the wire. */
+    branchName: string;
+    requiredApprovals?: number;
+    enablePush?: boolean;
+    enableStatusCheck?: boolean;
+    requireSignedCommits?: boolean;
+    dismissStaleApprovals?: boolean;
+    ignoreStaleApprovals?: boolean;
+    applyToAdmins?: boolean;
+    statusCheckContexts?: string[];
+}
+export interface BranchProtectionAttributes {
+    owner: string;
+    repo: string;
+    branchName: string;
+    requiredApprovals: number;
+    enablePush: boolean;
+    enableStatusCheck: boolean;
+    requireSignedCommits: boolean;
+    dismissStaleApprovals: boolean;
+    ignoreStaleApprovals: boolean;
+    applyToAdmins: boolean;
+    statusCheckContexts: string[];
+}
+export interface ForgejoBranchProtection extends Resource<'Forgejo.BranchProtection', BranchProtectionProps, BranchProtectionAttributes, never, ForgejoRequirements> {
+}
+export declare const ForgejoBranchProtection: import("alchemy").ResourceClass<ForgejoBranchProtection>;
+export declare const ForgejoBranchProtectionProvider: () => import("effect/Layer").Layer<Provider.Provider<ForgejoBranchProtection>, never, import("effect/unstable/http/HttpClient").HttpClient>;
+//# sourceMappingURL=branch-protection.d.ts.map

package/dist/forgejo/branch-protection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-protection.d.ts","sourceRoot":"","sources":["../../src/forgejo/branch-protection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAG7C,OAAO,EAAE,KAAK,mBAAmB,EAAmB,MAAM,eAAe,CAAC;AAG1E,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,OAAO,CAAC;IACpB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,oBAAoB,EAAE,OAAO,CAAC;IAC9B,qBAAqB,EAAE,OAAO,CAAC;IAC/B,oBAAoB,EAAE,OAAO,CAAC;IAC9B,aAAa,EAAE,OAAO,CAAC;IACvB,mBAAmB,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,uBAAwB,SAAQ,QAAQ,CACvD,0BAA0B,EAC1B,qBAAqB,EACrB,0BAA0B,EAC1B,KAAK,EACL,mBAAmB,CACpB;CAAG;AAEJ,eAAO,MAAM,uBAAuB,0DAGnC,CAAC;AAqCF,eAAO,MAAM,+BAA+B,6IAIzC,CAAC"}