@homeflare/alchemy 0.27.0 → 0.27.2

package/src/forgejo/values.ts

@@ -1,27 +1,19 @@
 /**
  * Wire coercions shared across Forgejo resources.
  *
- * ★ GITEA/ FORGEJO JSON USES snake_case ON THE WIRE and camelCase in props — each resource
+ * ★ GITEA/FORGEJO JSON USES snake_case ON THE WIRE and camelCase in props — each resource
  *   translates at the form boundary; these helpers only normalise values for comparison.
+ *
+ * ⛔ `text`/`bool`/`int` FROM THE HAND-ROLLED CLIENT ERA ARE GONE. They coerced values out of an
+ *   untyped `Record<string, unknown>` response. `@distilled.cloud/forgejo`'s operations decode
+ *   into typed structs (`Repository`, `Label`, `BranchProtection`, …), so an optional field is
+ *   already `string | undefined` / `boolean | undefined` — a plain `live.field ?? fallback` at
+ *   the call site replaces every one of their call sites, and a malformed response now fails the
+ *   operation's decode instead of silently coercing to a fallback.
  */
 
-export const text = (value: unknown, fallback = '') =>
-  typeof value === 'string' ? value : fallback;
-
 /** Forgejo returns label colours without `#`; declarations may include it. */
-export const color = (value: unknown) => text(value).replace(/^#/, '').toLowerCase();
-
-export const bool = (value: unknown, fallback = false) =>
-  value === undefined || value === null ? fallback : value === true || value === 1 || value === '1';
-
-export const int = (value: unknown, fallback = 0) => {
-  if (typeof value === 'number' && Number.isFinite(value)) return Math.trunc(value);
-  if (typeof value === 'string' && value.trim() !== '') {
-    const parsed = Number.parseInt(value, 10);
-    if (Number.isFinite(parsed)) return parsed;
-  }
-  return fallback;
-};
+export const color = (value: string) => value.replace(/^#/, '').toLowerCase();
 
 /** Wire arrays compared in sorted order — Gitea reshuffles nothing but callers should not depend on order. */
 export const stringArray = (value: unknown) =>

package/src/launchd/port-claims.ts

@@ -3,13 +3,12 @@
  * runtime-portable (no `Bun.*`, no `node:*`), so a future Linux consumer (systemd units, under
  * `/linux`) can import it unchanged.
  *
- * ★ MIRRORS house/nix's REGISTRY, NOT A NEW RULE. `lib-ports.nix` (house @ 92cff7f) collides on
- *   `lib.attrValues ports` alone — `dupes = lib.subtractLists (lib.unique vals) vals` — keying on
- *   the PORT NUMBER by itself; address and protocol are never read. `portClaimProblems` below keys
- *   the same way on purpose: it replaces that check for the jobs a kit stack declares, and a looser
- *   or stricter rule would silently diverge from the registry it takes over from. What that trades
- *   away — a wildcard bind beside a specific one on the same port both succeed, silently splitting
- *   traffic — is measured in docs/launchd-ports.md, not assumed.
+ * ★ KEYS ON THE PORT NUMBER ALONE, NOT A NEW RULE. `portClaimProblems` below matches the estate's
+ *   existing port-collision strictness — address and protocol never read — deliberately: a looser
+ *   or stricter rule here would be a second, inconsistent source of truth for jobs migrating off a
+ *   host's own port registry (still enforcing that same strictness until a job leaves it). What
+ *   this trades away — a wildcard bind beside a specific one on the same port both succeed,
+ *   silently splitting traffic — is measured in docs/launchd-ports.md, not assumed.
  * ★ IN THE STACK PROGRAM, NOT A PROVIDER — same shape as `catalogBinary()` (../release/catalog.ts).
  *   Two reasons, both structural to Alchemy 2.0.0-beta.79: Alchemy never diffs a first `create`
  *   whose props still hold an unresolved `Output`, and every mini job's `programArguments` carries
@@ -38,8 +37,8 @@ const describeAddress = (address: string | undefined): string => address ?? 'uns
 const describeOwner = (owner: string): string => (owner === '' ? '(empty owner)' : owner);
 
 /**
- * Everything wrong with a set of claims; empty when none collide. ★ KEYS ON `port` ALONE, exactly
- *   like `lib-ports.nix`'s `assertNoCollision` — see the file header for why.
+ * Everything wrong with a set of claims; empty when none collide. ★ KEYS ON `port` ALONE — see the
+ *   file header for why.
  */
 export const portClaimProblems = (claims: readonly PortClaim[]): string[] => {
   const found: string[] = [];

package/dist/cloudflare/client.d.ts

@@ -1,45 +0,0 @@
-/**
- * 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.
- *   `<estate>/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

@@ -1 +0,0 @@
-{"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/forgejo/client.d.ts

@@ -1,37 +0,0 @@
-/**
- * One authenticated call to the Forgejo (Gitea) API at `/api/v1`.
- *
- * ★ PLAIN `fetch`, NO TLS ESCAPE HATCH — your Forgejo host serves a real certificate on :443,
- *   and the local daemon on :3000 is loopback. There is no `rejectUnauthorized` switch to leave
- *   on by accident elsewhere.
- *
- * ⚠️ GITEA DOES NOT WRAP ANSWERS IN `{"data": ...}` THE WAY PVE DOES. MEASURED 2026-09-13 on
- *   the live daemon: `GET /api/v1/version` returns `{"version":"16.0.3"}`; `GET /api/v1/user`
- *   returns the user object; `GET /api/v1/orgs/HomeFlare/repos` returns a JSON array. A caller
- *   that unwraps a non-existent envelope sees `undefined` and calls a healthy object "absent".
- *
- * ⛔ THE TOKEN IS NEVER A PROP. Read `FORGEJO_TOKEN` from the environment at call time only.
- *   Alchemy persists attributes unencrypted and this estate's state store is Postgres dumped
- *   nightly — nothing stored may be a credential.
- */
-import * as Effect from 'effect/Effect';
-import * as HttpClient from 'effect/unstable/http/HttpClient';
-/**
- * The Forgejo instance, from `FORGEJO_URL`. Trailing slash stripped.
- *
- * ⛔ NO DEFAULT HOSTNAME. This used to fall back to the author's own instance, which is
- *   fine inside one estate and wrong in a published package: a consumer who forgets the
- *   variable would silently point at someone else's server rather than being told.
- * ⚠️ Read at CALL time, never at module scope — a value captured at import is pinned to
- *   whatever the first isolate saw.
- */
-export declare const apiBase: () => string;
-export declare class ForgejoError extends Error {
-    readonly status: number;
-    readonly method: string;
-    readonly path: string;
-    constructor(status: number, method: string, path: string, detail: string);
-}
-/** One JSON call. Returns the parsed body, or `undefined` when the response is empty (DELETE). */
-export declare const forgejo: <T>(method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', path: string, body?: Record<string, unknown>) => Effect.Effect<T, ForgejoError, HttpClient.HttpClient>;
-//# sourceMappingURL=client.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/forgejo/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,UAAU,MAAM,iCAAiC,CAAC;AAK9D;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,QAAO,MAQ1B,CAAC;AAkBF,qBAAa,YAAa,SAAQ,KAAK;IAEnC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM;IAHvB,YACW,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,EAIf;CACF;AAQD,kGAAkG;AAClG,eAAO,MAAM,OAAO,GAAI,CAAC,UACf,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,QAC7C,MAAM,SACL,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,0DAwD5B,CAAC"}

package/src/cloudflare/client.ts

@@ -1,76 +0,0 @@
-/**
- * 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.
- *   `<estate>/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 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';
-
-/** 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>;
-
-export class CloudflareApi extends Context.Service<CloudflareApi, Cloudflare>()(
-  'homeflare/CloudflareApi',
-) {}
-
-/**
- * ⚠️ 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 const makeClient = (options: { apiToken: string; fetch?: ClientFetch }): Cloudflare =>
-  new Cloudflare({
-    apiToken: options.apiToken,
-    ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
-  });
-
-/**
- * ⛔ FAIL CLOSED ON THE VALUE, NEVER ON THE VARIABLE EXISTING. AGENTS.md "the four that cost the
- *   most" §4: a denied OpenBao path renders the template EMPTY rather than erroring, and every
- *   Cloudflare call then answers 403 exactly like a revoked token — which sends the operator to
- *   Cloudflare to rotate a credential that was fine. Your deploy wrapper should write
- *   CLOUDFLARE_API_TOKEN from the stack's declared role, short-lived and scoped.
- */
-const 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.';
-
-const 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.';
-
-/**
- * ⛔ 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 const 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 value = Redacted.value(token);
-    if (value.length === 0) return yield* Effect.die(new Error(EMPTY_TOKEN));
-    return makeClient({ apiToken: value });
-  }),
-);

package/src/forgejo/client.ts

@@ -1,136 +0,0 @@
-/**
- * One authenticated call to the Forgejo (Gitea) API at `/api/v1`.
- *
- * ★ PLAIN `fetch`, NO TLS ESCAPE HATCH — your Forgejo host serves a real certificate on :443,
- *   and the local daemon on :3000 is loopback. There is no `rejectUnauthorized` switch to leave
- *   on by accident elsewhere.
- *
- * ⚠️ GITEA DOES NOT WRAP ANSWERS IN `{"data": ...}` THE WAY PVE DOES. MEASURED 2026-09-13 on
- *   the live daemon: `GET /api/v1/version` returns `{"version":"16.0.3"}`; `GET /api/v1/user`
- *   returns the user object; `GET /api/v1/orgs/HomeFlare/repos` returns a JSON array. A caller
- *   that unwraps a non-existent envelope sees `undefined` and calls a healthy object "absent".
- *
- * ⛔ THE TOKEN IS NEVER A PROP. Read `FORGEJO_TOKEN` from the environment at call time only.
- *   Alchemy persists attributes unencrypted and this estate's state store is Postgres dumped
- *   nightly — nothing stored may be a credential.
- */
-import * as Effect from 'effect/Effect';
-import * as HttpClient from 'effect/unstable/http/HttpClient';
-import * as HttpClientRequest from 'effect/unstable/http/HttpClientRequest';
-
-const PATH_PREFIX = '/api/v1';
-
-/**
- * The Forgejo instance, from `FORGEJO_URL`. Trailing slash stripped.
- *
- * ⛔ NO DEFAULT HOSTNAME. This used to fall back to the author's own instance, which is
- *   fine inside one estate and wrong in a published package: a consumer who forgets the
- *   variable would silently point at someone else's server rather than being told.
- * ⚠️ Read at CALL time, never at module scope — a value captured at import is pinned to
- *   whatever the first isolate saw.
- */
-export const apiBase = (): string => {
-  const raw = process.env['FORGEJO_URL'];
-  if (raw === undefined || raw.trim() === '') {
-    throw new Error(
-      'FORGEJO_URL is not set. Point it at your Forgejo instance, e.g. https://git.example.com',
-    );
-  }
-  return raw.trim().replace(/\/$/, '');
-};
-
-const token = (): Effect.Effect<string, ForgejoError> =>
-  Effect.gen(function* () {
-    const raw = process.env['FORGEJO_TOKEN'];
-    if (raw === undefined || raw.trim() === '') {
-      return yield* Effect.fail(
-        new ForgejoError(
-          0,
-          'GET',
-          '',
-          'FORGEJO_TOKEN is unset. Mint a scoped token and export it — never store it in Alchemy props.',
-        ),
-      );
-    }
-    return raw.trim();
-  });
-
-export class ForgejoError extends Error {
-  constructor(
-    readonly status: number,
-    readonly method: string,
-    readonly path: string,
-    detail: string,
-  ) {
-    super(`Forgejo ${method} ${path} -> ${String(status)}: ${detail}`);
-    this.name = 'ForgejoError';
-  }
-}
-
-/**
- * ⚠️ `Authorization: token <value>`, NOT `Bearer`. Gitea docs and MEASURED behaviour on this
- *   estate: Bearer is treated as OAuth2 and rejected; `token` is the documented API-key form.
- */
-const authorization = (value: string) => ({ Authorization: `token ${value}` });
-
-/** One JSON call. Returns the parsed body, or `undefined` when the response is empty (DELETE). */
-export const forgejo = <T>(
-  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
-  path: string,
-  body?: Record<string, unknown>,
-) =>
-  Effect.gen(function* () {
-    const credential = yield* token();
-    const url = `${apiBase()}${PATH_PREFIX}/${path.replace(/^\//, '')}`;
-    /**
-     * ★ THROUGH `HttpClient`, NOT THE GLOBAL `fetch` — the idiom Alchemy's own providers follow
-     *   (src/Hetzner/Providers.ts builds on `FetchHttpClient.layer`; there is no bare fetch in its
-     *   Docker, Kubernetes or GitHub providers). It buys a typed error channel, interruption when
-     *   a plan is cancelled, the runtime's tracing, and a client a test can replace without
-     *   monkey-patching a global. <estate>/proxmox/src/resource.ts carries the same note.
-     */
-    const client = yield* HttpClient.HttpClient;
-    /**
-     * ⛔ THE CONTENT TYPE GOES ON `bodyText`, NOT IN THE HEADER MAP, AND PUTTING IT IN BOTH IS HOW
-     *   THIS PACKAGE SHIPPED UNABLE TO WRITE AT ALL.
-     *
-     * 🔴 THE BUG, MEASURED THE FIRST TIME A WRITE WAS EVER ATTEMPTED. The header map DID carry
-     *   `Content-Type: application/json` — and `bodyText(s)` with no second argument sets
-     *   `text/plain` and OVERWRITES it, because it is piped AFTER `setHeaders`. Forgejo answered
-     *       422 {"message":"[]: Unsupported Content-Type"}
-     *   on `PATCH orgs/homeflare/labels/1`. Every create and every update in every family here was
-     *   broken, identically, from the day the client was written.
-     *
-     * ⛔ NOTHING CAUGHT IT BECAUSE NOTHING HAD EVER WRITTEN. The only credential on the shelf was
-     *   `mcp-read`, which answers 403 before a request body is ever parsed — so read, adopt, diff
-     *   and plan all worked perfectly and the write path had literally never executed. A provider
-     *   that has never performed its own writes is not a tested provider, whatever the plan says.
-     *
-     * ⚠️ `bodyJsonUnsafe` WOULD ALSO WORK. `bodyText` with an explicit type is used instead
-     *   because it makes the content type visible at the call site, which is the thing that was
-     *   invisible before.
-     */
-    const request = HttpClientRequest.make(method)(url).pipe(
-      HttpClientRequest.setHeaders({ ...authorization(credential), Accept: 'application/json' }),
-      body === undefined
-        ? (self) => self
-        : HttpClientRequest.bodyText(JSON.stringify(body), 'application/json'),
-    );
-    const response = yield* client
-      .execute(request)
-      .pipe(Effect.mapError((cause) => new ForgejoError(0, method, path, String(cause))));
-    // ⛔ Status first, body once — a Gitea error body is JSON but a proxy's 502 is not.
-    if (response.status < 200 || response.status >= 300) {
-      const detail = yield* response.text.pipe(Effect.orElseSucceed(() => ''));
-      return yield* Effect.fail(
-        new ForgejoError(response.status, method, path, detail.slice(0, 300)),
-      );
-    }
-    // ⚠️ 204 AND AN EMPTY BODY ARE REAL: a label DELETE answers no content, and `json` on an empty
-    //   body fails. Read text once and parse only when there is something to parse.
-    const text = yield* response.text.pipe(
-      Effect.mapError((cause) => new ForgejoError(0, method, path, String(cause))),
-    );
-    // ⚠️ PUT/DELETE on actions secrets and hooks often answer 201/204 with no body — same trap as DELETE.
-    return (text === '' ? undefined : JSON.parse(text)) as T;
-  });