@homeflare/alchemy 0.28.0 → 0.29.1

package/src/github/repository-ruleset-providers.ts

@@ -0,0 +1,46 @@
+/**
+ * `repoPolicyProviders` — the documented stack wiring for `RepositoryRuleset` (directly, or
+ * through `declareRepoPolicy` / `declareRepoBaseline`): `GitHub.providers()` and
+ * `RepositoryRulesetProvider()`, composed so the whole thing typechecks and needs nothing
+ * further from the stack.
+ *
+ *     providers: repoPolicyProviders()
+ *
+ * ⛔ WHY THIS EXISTS — MEASURED 2026-09-24 (homeflare-builds bump PR 6, tsc). Writing the two
+ *   providers side by side, `Layer.mergeAll(GitHub.providers(), RepositoryRulesetProvider())`,
+ *   type-errors: `RepositoryRulesetProvider()`'s handlers call `octokitFor`, which needs
+ *   `GitHubCredentials` — a requirement of the PROVIDER's layer, correctly inferred by
+ *   `Provider.succeed` from `repositoryRulesetHandlers` in repository-ruleset.ts. Merging two
+ *   layers does not thread one's output into the other's requirement; `RepositoryRulesetProvider()`
+ *   still needs `GitHubCredentials` fed in. `GitHub.providers()` is the only thing here that
+ *   resolves credentials (env, stored PAT, `gh` CLI, or OAuth — see `alchemy/src/GitHub/
+ *   Providers.ts`), and — because it chains `Layer.provideMerge(Credentials.fromAuthProvider(…))`
+ *   internally rather than `Layer.provide` — its own OUTPUT includes `GitHubCredentials`
+ *   alongside `GitHub.Providers`. `Layer.provideMerge(github)` on `RepositoryRulesetProvider()`
+ *   both supplies that requirement AND keeps `github`'s own output merged in for any
+ *   `GitHub.Repository`/`GitHub.Ruleset` the caller also declares. `github` is built once and
+ *   referenced twice below — Effect's layer memoization (by reference) builds it once, not
+ *   twice, not twice against the auth provider either.
+ *
+ * ★ THIS IS ONLY HALF OF 2026-09-24's FIX. The other half — `RepositoryRuleset`'s own `Resource<>`
+ *   declaration no longer naming `GitHubCredentials` in its 5th (`Providers`) slot — lives in
+ *   repository-ruleset.ts's file header; that half is what let a stack BODY calling
+ *   `declareRepoPolicy`/`declareRepoBaseline` typecheck at all. Composing the providers
+ *   correctly, as this function does, does not by itself fix a body that still requires
+ *   `GitHubCredentials` directly.
+ *
+ * ⚠️ DON'T ALSO MERGE A SEPARATE `GitHub.providers()` CALL IN. `github` here is one Layer
+ *   object referenced twice, which Effect's layer memoization (by reference, ADVERSARIAL
+ *   REVIEW 2026-09-24: confirmed against `effect@4.0.0-rc.115`'s own `MemoMap`) builds once. A
+ *   stack that ALSO writes its own `GitHub.providers()` alongside this function's result is a
+ *   second, distinct Layer object — a genuine second credential resolution, not shared with
+ *   this one. Get every GitHub resource's providers from this one call.
+ */
+import * as GitHub from 'alchemy/GitHub';
+import * as Layer from 'effect/Layer';
+import { RepositoryRulesetProvider } from './repository-ruleset.ts';
+
+export const repoPolicyProviders = (options?: GitHub.ProvidersOptions) => {
+  const github = GitHub.providers(options);
+  return Layer.mergeAll(github, RepositoryRulesetProvider().pipe(Layer.provideMerge(github)));
+};

package/src/github/repository-ruleset-wire.test.ts

@@ -32,35 +32,46 @@ function makeCapturingFetch(captured: CapturedRequest[]): typeof fetch {
 }
 
 describe('does Octokit forward an untyped extra body field to the wire?', () => {
-  test('require_extra_approval_for_unattributed_changes survives createRepoRuleset', async () => {
-    const captured: CapturedRequest[] = [];
-    const octokit = new Octokit({
-      auth: 'fake-token-not-a-real-credential',
-      request: { fetch: makeCapturingFetch(captured) },
-    });
+  // K1 (2026-09-23): both values are modeled now, not only `false` — 8 live rulesets (aop,
+  // cloudflareforms, doesthishelp-workeropen, homeflare-anyauth, homeflare-desktop, loggarr,
+  // magictransit, proxmox-tb4; re-read live 2026-09-23) carry `true`, so this measurement needs
+  // both, not just the one value this resource used to be able to send.
+  test.each([false, true])(
+    'require_extra_approval_for_unattributed_changes: %p survives createRepoRuleset',
+    async (value) => {
+      const captured: CapturedRequest[] = [];
+      const octokit = new Octokit({
+        auth: 'fake-token-not-a-real-credential',
+        request: { fetch: makeCapturingFetch(captured) },
+      });
 
-    const body = desiredWireRuleset({
-      owner: 'taslabs-net',
-      repository: 'widgets',
-      name: 'main',
-      rules: {
-        pullRequest: {
-          requiredApprovingReviewCount: 0,
-          allowedMergeMethods: ['squash'],
-          extraApprovalForUnattributedChanges: false,
+      const body = desiredWireRuleset({
+        owner: 'taslabs-net',
+        repository: 'widgets',
+        name: 'main',
+        rules: {
+          pullRequest: {
+            requiredApprovingReviewCount: 0,
+            allowedMergeMethods: ['squash'],
+            extraApprovalForUnattributedChanges: value,
+          },
         },
-      },
-    });
+      });
 
-    await octokit.rest.repos.createRepoRuleset({ owner: 'taslabs-net', repo: 'widgets', ...body });
+      await octokit.rest.repos.createRepoRuleset({
+        owner: 'taslabs-net',
+        repo: 'widgets',
+        ...body,
+      });
 
-    expect(captured).toHaveLength(1);
-    const sent = captured[0]?.body as {
-      rules?: { type: string; parameters?: Record<string, unknown> }[];
-    };
-    const pr = sent?.rules?.find((r) => r.type === 'pull_request');
-    // MEASURED: this is what actually crossed the wire, not what Octokit's types say is legal.
-    expect(pr?.parameters?.require_extra_approval_for_unattributed_changes).toBe(false);
-    expect(pr?.parameters?.allowed_merge_methods).toEqual(['squash']);
-  });
+      expect(captured).toHaveLength(1);
+      const sent = captured[0]?.body as {
+        rules?: { type: string; parameters?: Record<string, unknown> }[];
+      };
+      const pr = sent?.rules?.find((r) => r.type === 'pull_request');
+      // MEASURED: this is what actually crossed the wire, not what Octokit's types say is legal.
+      expect(pr?.parameters?.require_extra_approval_for_unattributed_changes).toBe(value);
+      expect(pr?.parameters?.allowed_merge_methods).toEqual(['squash']);
+    },
+  );
 });

package/src/github/repository-ruleset.ts

@@ -38,11 +38,33 @@
  *   meant to allow. `octokitFor`/`GitHubCredentials` are upstream's own EXPORTED building
  *   blocks (S23's second clause: reuse Alchemy's own client construction), so the client itself
  *   is not hand-rolled — only the choice of Octokit over distilled is a recorded divergence.
+ *
+ * ⛔ CREDENTIALS BELONG TO THE PROVIDER'S LAYER, NOT THE RESOURCE'S DECLARATION — MEASURED
+ *   2026-09-24 (homeflare-builds bump PR 6, tsc TS2345). The `Resource<Type, Props, Attributes,
+ *   Binding, Providers>` 5th type parameter had `GitHubCredentials` here; that puts the
+ *   credential requirement on every `yield* RepositoryRuleset(...)` CALL SITE (see
+ *   `alchemy/src/Resource.ts#ResourceClass`: `Req = R["Providers"] extends undefined ?
+ *   Provider<R> : R["Providers"]`), so a STACK BODY that merely declares the resource would
+ *   itself need `GitHubCredentials` in its own effect context — which a stack body cannot
+ *   produce (`Alchemy.Stack`'s own type, `alchemy/src/Stack.ts#ProviderServices`, is a closed
+ *   union of tagged marker interfaces — `ProviderCollectionLike | Provider<any> |
+ *   EnvironmentLike | CredentialsLike | DockerLike` — and `GitHubCredentials` matches none of
+ *   them structurally). VERIFIED against upstream `Ruleset` (`node_modules/alchemy/src/GitHub/
+ *   Ruleset.ts`): its 5th slot is `GitHub.Providers`, the ProviderCollection tag `GitHub.
+ *   providers()` OUTPUTS — never the raw `GitHubCredentials` service upstream's OWN provider
+ *   handlers pull in via `octokitFor`. `GitHubCredentials` stays confined to the PROVIDER's
+ *   layer requirement (`Provider.succeed`'s inferred `ReadReq | DiffReq | ReconcileReq |
+ *   DeleteReq`, below), never the declaration's. Omitting the 5th parameter here defaults it to
+ *   `undefined`, so the declaration's own requirement becomes `Provider<RepositoryRuleset>` —
+ *   itself a `Provider<any>`, a real `ProviderServices` member — matching the pattern a
+ *   standalone (non-collection) resource actually needs. See `repoPolicyProviders()` in
+ *   repository-ruleset-providers.ts for the layer composition this now requires (the provider
+ *   still needs `GitHubCredentials` fed in — that half of the fix was already correct, per
+ *   `docs/repository-ruleset.md`).
  */
 import { Resource } from 'alchemy';
 import { Unowned } from 'alchemy/AdoptPolicy';
 import { isResolved } from 'alchemy/Diff';
-import type { GitHubCredentials } from 'alchemy/GitHub';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
 import {
@@ -75,8 +97,10 @@ export interface RepositoryRuleset extends Resource<
   'GitHub.RepositoryRuleset',
   RepositoryRulesetProps,
   RepositoryRulesetAttributes,
-  never,
-  GitHubCredentials
+  never
+  // ⛔ NO 5th (`Providers`) ARGUMENT — see the file header. Defaulting it to `undefined` makes
+  // a `yield* RepositoryRuleset(...)` call site require `Provider<RepositoryRuleset>`, not
+  // `GitHubCredentials`; the credential requirement lives on the PROVIDER below instead.
 > {}
 
 export const RepositoryRuleset = Resource<RepositoryRuleset>('GitHub.RepositoryRuleset', {

package/src/litellm/fake-litellm.ts

@@ -1,22 +1,35 @@
 /**
- * A loopback `Bun.serve` fake of LiteLLM's `/config/pass_through_endpoint` routes — TEST ONLY,
- * never imported by `index.ts` (the netbox/proxmox house convention for test-only helpers).
+ * A fake of LiteLLM's `/config/pass_through_endpoint` routes for tests — TEST ONLY, never imported
+ * by `index.ts` (the netbox/forgejo house convention for test-only helpers). Mirrors
+ * `../netbox/fake-netbox.ts`/`../forgejo/fake-forgejo.ts`: a `fetch` function handed to Effect's
+ * real `FetchHttpClient` through its `Fetch` reference, so a test exercises distilled's REAL path
+ * assembly, JSON encode/decode and status→typed-error matching (`BadRequest`, `NotFound`, …) —
+ * nothing about that matching is re-implemented here, only the wire responses a scenario needs.
  *
  * ★ MODELS THE WHOLE-FIELD READ-MODIFY-WRITE ON PURPOSE. `general_settings.pass_through_endpoints`
- *   is ONE field (client.ts's header), so every mutation here reads the CURRENT row list, waits
- *   (so two concurrent requests can interleave), then writes back what it captured — not what is
- *   there by the time it writes. Two `create` calls that race lose one row, exactly like the
- *   vendor field would without the client's per-base-URL semaphore serialising them.
+ *   is ONE field (operations.ts's header), so every mutation here reads the CURRENT row list,
+ *   awaits (so two concurrent calls can interleave — no real socket needed, `fetch` is just an
+ *   async function the runtime awaits), then writes back what it captured — not what is there by
+ *   the time it writes. Two `create` calls that race lose one row, exactly like the vendor field
+ *   would without `operations.ts`'s per-base-URL semaphore serialising them.
  * ⚠️ WHAT THIS FAKE DOES NOT MODEL: PROXY_ADMIN vs. a lesser role for most routes (any correct
- *   bearer token is accepted); and update-of-a-missing-id, which is not measured at the tag — this
- *   fake 400s it, the same status a missing delete gets, as a documented TEST SIMPLIFICATION, not a
- *   vendor fact (docs/litellm.md says so too). `forbidDelete` is the one exception: it models the
- *   real asymmetry client.ts's header describes — `DELETE` routes through
- *   `update_config_general_settings`, which 400s `not_allowed_access` for a non-PROXY_ADMIN caller
- *   (or a disconnected DB) on a row that is genuinely still live, the SAME status a missing-id
- *   delete gets (proxy_server.py:16389-16416 at v1.100.0).
+ *   bearer token is accepted). `forbidDelete` is the one exception: it models the real asymmetry
+ *   `operations.ts`'s header describes — `DELETE` routes through `update_config_general_settings`,
+ *   which 400s `not_allowed_access` for a non-PROXY_ADMIN caller (or a disconnected DB) on a row
+ *   that is genuinely still live, the SAME status a missing-id delete gets (proxy_server.py:
+ *   16389-16416 at v1.100.0).
+ * ⚠️ UPDATE-OF-A-MISSING-ID IS 404, NOT 400 — corrected by this migration. The retired hand-rolled
+ *   fake 400'd it as "not measured at the tag, a documented test simplification". The distilled
+ *   SDK's own `patches/misc/update_pass_through_endpoints_*.json` cites the real source
+ *   (`pass_through_endpoints.py`'s `update_pass_through_endpoints` at the tag): unlike DELETE, this
+ *   route raises a genuine, unambiguous `HTTPException(404)` for a missing id, distinct from the
+ *   400 `update_config_general_settings` raises for the trailing auth/DB-disconnected write. This
+ *   fake now matches that measured vendor behaviour.
  */
-import type { PassThroughGenericEndpoint } from './generated/pass-through.ts';
+import type { PassThroughGenericEndpoint } from '@distilled.cloud/litellm/misc';
+
+/** RFC 2606 placeholder — never a real host. Shared across tests, like `../netbox/fake-netbox.ts`. */
+export const FAKE_BASE = 'https://litellm.example.com';
 
 export interface FakeRequest {
   readonly method: string;
@@ -24,15 +37,17 @@ export interface FakeRequest {
 }
 
 export interface FakeLitellm {
-  readonly url: string;
+  readonly fetch: typeof globalThis.fetch;
   readonly rows: () => readonly PassThroughGenericEndpoint[];
   readonly requests: () => readonly FakeRequest[];
-  readonly stop: () => void;
 }
 
 const RACE_WINDOW_MS = 15;
 const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
 
+const json = (status: number, body: unknown) =>
+  new Response(JSON.stringify(body), { headers: { 'content-type': 'application/json' }, status });
+
 export const startFakeLitellm = (options?: {
   readonly masterKey?: string;
   readonly seed?: readonly PassThroughGenericEndpoint[];
@@ -44,73 +59,63 @@ export const startFakeLitellm = (options?: {
   let rows: PassThroughGenericEndpoint[] = [...(options?.seed ?? [])];
   const requests: FakeRequest[] = [];
 
-  const json = (status: number, body: unknown) =>
-    new Response(JSON.stringify(body), { headers: { 'content-type': 'application/json' }, status });
+  const fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const url = new URL(request.url);
+    requests.push({ method: request.method, path: `${url.pathname}${url.search}` });
+    const auth = request.headers.get('authorization');
+    if (auth !== `Bearer ${masterKey}`) return json(401, { detail: 'invalid api key' });
+    if (
+      url.pathname !== '/config/pass_through_endpoint' &&
+      !url.pathname.startsWith('/config/pass_through_endpoint/')
+    ) {
+      return json(404, { detail: 'not found' });
+    }
 
-  const server = Bun.serve({
-    // ⚠️ Loopback, not the wildcard default — see proxmox/fake-pve-lxc.ts for the race.
-    hostname: '127.0.0.1',
-    port: 0,
-    fetch: async (req) => {
-      const url = new URL(req.url);
-      requests.push({ method: req.method, path: url.pathname });
-      const auth = req.headers.get('authorization');
-      if (auth !== `Bearer ${masterKey}`) return json(401, { detail: 'invalid api key' });
-      if (
-        url.pathname !== '/config/pass_through_endpoint' &&
-        !url.pathname.startsWith('/config/pass_through_endpoint/')
-      ) {
-        return json(404, { detail: 'not found' });
-      }
+    if (request.method === 'GET') {
+      const endpointId = url.searchParams.get('endpoint_id');
+      const filtered = endpointId === null ? rows : rows.filter((row) => row.id === endpointId);
+      return json(200, { endpoints: filtered });
+    }
 
-      if (req.method === 'GET') {
-        const endpointId = url.searchParams.get('endpoint_id');
-        const filtered = endpointId === null ? rows : rows.filter((row) => row.id === endpointId);
-        return json(200, { endpoints: filtered });
-      }
+    if (request.method === 'POST' && url.pathname === '/config/pass_through_endpoint') {
+      const body = (await request.json()) as PassThroughGenericEndpoint;
+      const before = rows; // ★ captured before the window — the race the semaphore prevents
+      await sleep(RACE_WINDOW_MS);
+      rows = [...before, { ...body, is_from_config: false }];
+      return json(200, { body: {} });
+    }
 
-      if (req.method === 'POST' && url.pathname === '/config/pass_through_endpoint') {
-        const body = (await req.json()) as PassThroughGenericEndpoint;
-        const before = rows; // ★ captured before the window — the race the semaphore prevents
-        await sleep(RACE_WINDOW_MS);
-        rows = [...before, { ...body, is_from_config: false }];
-        return json(200, {});
-      }
-
-      if (req.method === 'POST' && url.pathname.startsWith('/config/pass_through_endpoint/')) {
-        const id = decodeURIComponent(url.pathname.slice('/config/pass_through_endpoint/'.length));
-        const patch = (await req.json()) as Partial<PassThroughGenericEndpoint>;
-        const before = rows;
-        await sleep(RACE_WINDOW_MS);
-        const index = before.findIndex((row) => row.id === id);
-        if (index === -1) return json(400, { detail: `No pass-through endpoint with id=${id}` });
-        // ⚠️ `exclude_none`-shaped: only keys the patch actually carries are merged, matching
-        //   client.ts's `updateBody` never sending an unset/null field (pass-through-form.ts).
-        const merged = { ...before[index], ...patch };
-        rows = before.map((row, i) => (i === index ? (merged as PassThroughGenericEndpoint) : row));
-        return json(200, {});
-      }
+    if (request.method === 'POST' && url.pathname.startsWith('/config/pass_through_endpoint/')) {
+      const id = decodeURIComponent(url.pathname.slice('/config/pass_through_endpoint/'.length));
+      const patch = (await request.json()) as Partial<PassThroughGenericEndpoint>;
+      const before = rows;
+      await sleep(RACE_WINDOW_MS);
+      const index = before.findIndex((row) => row.id === id);
+      // ⚠️ 404, not 400 — see the file header.
+      if (index === -1) return json(404, { detail: `Endpoint with ID '${id}' not found` });
+      // ⚠️ `exclude_none`-shaped: only keys the patch actually carries are merged, matching
+      //   operations.ts's `updateBody` never sending an unset/null field (pass-through-form.ts).
+      const merged = { ...before[index], ...patch };
+      rows = before.map((row, i) => (i === index ? (merged as PassThroughGenericEndpoint) : row));
+      return json(200, { body: {} });
+    }
 
-      if (req.method === 'DELETE' && url.pathname === '/config/pass_through_endpoint') {
-        const id = url.searchParams.get('endpoint_id');
-        if (forbidDelete) return json(400, { error: 'not_allowed_access' });
-        const before = rows;
-        await sleep(RACE_WINDOW_MS);
-        if (!before.some((row) => row.id === id)) {
-          return json(400, { detail: `No pass-through endpoint with id=${String(id)}` });
-        }
-        rows = before.filter((row) => row.id !== id);
-        return json(200, { endpoints: rows });
+    if (request.method === 'DELETE' && url.pathname === '/config/pass_through_endpoint') {
+      const id = url.searchParams.get('endpoint_id');
+      if (forbidDelete) return json(400, { error: 'not_allowed_access' });
+      const before = rows;
+      await sleep(RACE_WINDOW_MS);
+      if (!before.some((row) => row.id === id)) {
+        return json(400, { detail: `No pass-through endpoint with id=${String(id)}` });
       }
+      rows = before.filter((row) => row.id !== id);
+      return json(200, { endpoints: rows });
+    }
 
-      return json(405, { detail: `unhandled ${req.method} ${url.pathname}` });
-    },
-  });
+    return json(405, { detail: `unhandled ${request.method} ${url.pathname}` });
+  }) as typeof globalThis.fetch;
 
-  return {
-    requests: () => [...requests],
-    rows: () => [...rows],
-    stop: () => server.stop(true),
-    url: server.url.toString().replace(/\/$/, ''),
-  };
+  return { fetch, requests: () => [...requests], rows: () => [...rows] };
 };

package/src/litellm/fake-stack.ts

@@ -12,13 +12,13 @@
  * ★ NOT alchemy/Test/Bun — same reasoning as openbao/fake-stack.ts: no CLI profile/credentials
  *   files, no file logger. Just the provider, an in-memory state store, and the stack's services.
  */
+import { credentials } from '@distilled.cloud/litellm/Credentials';
 import * as Alchemy from 'alchemy';
 import { AdoptPolicy } from 'alchemy/AdoptPolicy';
 import { provideFreshArtifactStore } from 'alchemy/Artifacts';
 import * as Effect from 'effect/Effect';
 import * as Layer from 'effect/Layer';
 import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
-import { type LitellmCreds, litellmCredentialsLayerFor } from './credentials.ts';
 import { LiteLLMPassThroughEndpointProvider } from './pass-through-endpoint.ts';
 
 /** The planned action for each resource, deletions included, keyed by FQN. */
@@ -53,13 +53,20 @@ const actionsOf = (plan: PlanView): Planned => {
 /**
  * ⚠️ CREDENTIALS/HTTPCLIENT ARE PROVIDED AROUND `deploy`, NOT BAKED INTO THE PROVIDER LAYER.
  *   `Provider.effect`'s own construction effect is `Effect.succeed(...)` (pass-through-endpoint.ts)
- *   — it never actually reads `LitellmCredentials`/`HttpClient`; only the HANDLERS it returns do,
- *   and those run later, whenever `Apply.ts` calls `provider.reconcile`/`read`/`delete`. Effect
+ *   — it never actually reads `Credentials`/`HttpClient`; only the HANDLERS it returns do, and
+ *   those run later, whenever `Apply.ts` calls `provider.reconcile`/`read`/`delete`. Effect
  *   resolves a `yield*`'s service from whatever ambient context wraps the CALL SITE, so the layers
  *   those handlers need must wrap the whole plan+apply pipeline below, exactly where openbao's
  *   fake-stack.ts wraps `BaoEnv` around its own `deploy`.
+ * ★ `fetchFn` IS `startFakeLitellm(...).fetch` (fake-litellm.ts) — this harness never opens a real
+ *   socket; `FetchHttpClient.Fetch` is the seam the SDK's protocol layer calls through, same as
+ *   `../netbox/fake-netbox.ts`'s `fakeNetboxLayer`.
  */
-export const fakeStack = (creds: LitellmCreds, name = 'PassThroughStack'): FakeStack => {
+export const fakeStack = (
+  creds: { readonly apiKey: string; readonly baseUrl: string },
+  fetchFn: typeof globalThis.fetch,
+  name = 'PassThroughStack',
+): FakeStack => {
   const state = Alchemy.inMemoryState();
   const providers = LiteLLMPassThroughEndpointProvider();
   const stack = Alchemy.Stack as unknown as (
@@ -83,8 +90,9 @@ export const fakeStack = (creds: LitellmCreds, name = 'PassThroughStack'): FakeS
     }).pipe(
       options.adopt === undefined ? (e) => e : Effect.provideService(AdoptPolicy, options.adopt),
       Effect.provideService(Alchemy.Stage, 'test'),
-      Effect.provide(litellmCredentialsLayerFor(creds)),
+      Effect.provide(credentials(creds)),
       Effect.provide(FetchHttpClient.layer),
+      Effect.provide(Layer.succeed(FetchHttpClient.Fetch, fetchFn)),
       Effect.scoped,
     );
 

package/src/litellm/index.ts

@@ -2,32 +2,18 @@
  * LiteLLM providers for Alchemy.
  *
  * ⛔ THIS BARREL IS THE PUBLIC API, deliberately smaller than the directory — `fake-litellm.ts`
- *   and the internals `pass-through-form.ts`/`client.ts` need but a consumer should not depend on
- *   directly are not re-exported here (netbox/index.ts's own rule).
+ *   and the internals `pass-through-form.ts`/`operations.ts` need but a consumer should not depend
+ *   on directly are not re-exported here (netbox/index.ts's own rule).
+ * ★ CREDENTIALS AND TYPES NOW COME FROM `@distilled.cloud/litellm` ITSELF (2026-09-24, moved off a
+ *   hand-rolled `client.ts`/`credentials.ts` the same way `/netbox` and `/forgejo` did) — a
+ *   consumer building its own credentials layer imports `Credentials`/`CredentialsFromEnv`/
+ *   `credentials` from `@distilled.cloud/litellm/Credentials` directly, not through this barrel.
  */
-export {
-  LITELLM_PROXY_API_KEY_ENV,
-  LITELLM_PROXY_URL_ENV,
-  LitellmCredentials,
-  type LitellmCreds,
-  LitellmCredentialsError,
-  litellmCredentialsLayer,
-  litellmCredentialsLayerFor,
-} from './credentials.ts';
-export {
-  LITELLM_OPERATIONS,
-  LitellmBadRequestError,
-  type LitellmError,
-  LitellmHttpError,
-  type LitellmRequirements,
-  LitellmTransportError,
-  LitellmUnauthorizedError,
-} from './client.ts';
 export type {
   PassThroughEndpointResponse,
   PassThroughGenericEndpoint,
   PassThroughGuardrailSettings,
-} from './generated/pass-through.ts';
+} from '@distilled.cloud/litellm/misc';
 export {
   LiteLLMPassThroughEndpoint,
   LiteLLMPassThroughEndpointProvider,

package/src/litellm/operations.ts

@@ -0,0 +1,149 @@
+/**
+ * The four LiteLLM `/config/pass_through_endpoint*` calls this package writes to and reads from —
+ * now through `@distilled.cloud/litellm`'s typed operations (S23), not a hand-rolled `HttpClient`
+ * client. `client.ts` is retired; nothing else in this package imported it.
+ *
+ * ⛔ STILL WRAPPED IN A PER-BASE-URL SEMAPHORE, UNCHANGED FROM `client.ts`. LiteLLM stores every
+ *   pass-through endpoint in ONE `general_settings.pass_through_endpoints` list
+ *   (`pass_through_endpoints.py` at tag v1.100.0, mirrored in the SDK's own `misc.ts` docstrings),
+ *   so create/update/delete are each a read-modify-write of the WHOLE list through
+ *   `update_config_general_settings`. Two of this package's own calls racing each other — two
+ *   endpoints created in the same deploy — would each read the list, add their own row and write
+ *   it back, and the second write would silently drop the first row. The SDK has no opinion on
+ *   this: it is a quirk of how THIS vendor stores the resource, not a distilled protocol concern,
+ *   so it stays here, one layer above the typed calls. One permit per proxy serialises this
+ *   package's own writes; it cannot serialise against the LiteLLM UI or a second deploy process,
+ *   which is why `pass-through-endpoint.ts`'s `reconcile` reads back after writing rather than
+ *   trusting the call that just returned (docs/litellm.md).
+ * ⛔ NO STATUS SNIFFING (S21). Every failure the SDK's own typed operations declare — `BadRequest`
+ *   (400), `NotFound` (404 on update only), `UnprocessableEntity` (422) plus the shared
+ *   `Unauthorized`/`TooManyRequests`/`InternalServerError`/`BadGateway`/`ServiceUnavailable`/
+ *   `GatewayTimeout` every operation carries — is a distilled patch's doing
+ *   (`@distilled.cloud/litellm`'s own `patches/misc/*.json`, applied at generation time), never a
+ *   status check here or in `pass-through-endpoint.ts`. Deleting an id LiteLLM does not have
+ *   answers `BadRequest` (measured against the tag's `pass_through_endpoint_delete` — the id is
+ *   looked up in the list and a miss raises `HTTPException(400)`, not 404) — but so does a
+ *   genuinely-live row when the caller isn't PROXY_ADMIN, or the DB is disconnected. Telling those
+ *   apart by re-listing, not by the `BadRequest`'s message text, is `pass-through-endpoint.ts`'s
+ *   `deletePassThroughEndpoint`'s own job (S21 — a status-and-a-real-read decision, never body
+ *   text) — this file only forwards the typed error.
+ */
+import * as misc from '@distilled.cloud/litellm/misc';
+import { Credentials } from '@distilled.cloud/litellm/Credentials';
+import type { LitellmOpContext } from '@distilled.cloud/litellm/Protocol';
+import type { ConfigError } from '@distilled.cloud/litellm/Errors';
+import * as Effect from 'effect/Effect';
+import * as Semaphore from 'effect/Semaphore';
+
+export type { LitellmOpContext } from '@distilled.cloud/litellm/Protocol';
+export type LitellmRequirements = LitellmOpContext;
+export type {
+  PassThroughEndpointResponse,
+  PassThroughGenericEndpoint,
+  PassThroughGuardrailSettings,
+} from '@distilled.cloud/litellm/misc';
+
+const semaphores = new Map<string, Semaphore.Semaphore>();
+
+/** One semaphore per base URL, created on first use. Never `Hash.structure` (S18) — a plain Map key. */
+const semaphoreFor = (baseUrl: string): Effect.Effect<Semaphore.Semaphore> =>
+  Effect.sync(() => {
+    const existing = semaphores.get(baseUrl);
+    if (existing !== undefined) return existing;
+    const created = Semaphore.makeUnsafe(1);
+    semaphores.set(baseUrl, created);
+    return created;
+  });
+
+/**
+ * Serialises a write against this call's own base URL — see the file header.
+ *
+ * Resolving `Credentials` can itself fail typed (`ConfigError` — S20/S24, credentials.ts), so
+ * the return type carries that alongside the wrapped operation's own error `E`; every call
+ * site's declared error type already includes `ConfigError` as a member of the SDK's shared
+ * `LitellmOpError` (protocol.ts), so this widening is a no-op for callers.
+ */
+const mutate = <A, E>(
+  io: Effect.Effect<A, E, LitellmOpContext>,
+): Effect.Effect<A, E | ConfigError, LitellmOpContext> =>
+  Effect.gen(function* () {
+    const resolve = yield* Credentials;
+    const creds = yield* resolve;
+    const semaphore = yield* semaphoreFor(creds.apiBaseUrl);
+    return yield* semaphore.withPermits(1)(io);
+  });
+
+/** GET /config/pass_through_endpoint — every row, config-file and DB alike. Not under the semaphore: reads don't race the field. */
+export const listPassThroughEndpoints = (): Effect.Effect<
+  readonly misc.PassThroughGenericEndpoint[],
+  misc.GetPassThroughEndpointsConfigPassThroughEndpointGetError,
+  LitellmOpContext
+> =>
+  misc
+    .getPassThroughEndpointsConfigPassThroughEndpointGet({})
+    .pipe(Effect.map((response) => response.endpoints));
+
+/** POST /config/pass_through_endpoint. `body` carries `id` — see pass-through-form.ts. */
+export const createPassThroughEndpoint = (
+  body: misc.PassThroughGenericEndpoint,
+): Effect.Effect<
+  void,
+  misc.CreatePassThroughEndpointsConfigPassThroughEndpointPostError,
+  LitellmOpContext
+> => mutate(misc.createPassThroughEndpointsConfigPassThroughEndpointPost(body).pipe(Effect.asVoid));
+
+/**
+ * POST /config/pass_through_endpoint/{endpoint_id}. Merges with `exclude_none` — see
+ * pass-through-form.ts. `body` is `pass-through-form.ts`'s own `UpdateBody`, not a blanket
+ * `Partial<>` — `path`/`target` are the two fields the SDK's request type still requires
+ * non-optionally on an update.
+ */
+export const updatePassThroughEndpoint = (
+  endpointId: string,
+  body: Partial<Omit<misc.PassThroughGenericEndpoint, 'path' | 'target'>> &
+    Pick<misc.PassThroughGenericEndpoint, 'path' | 'target'>,
+): Effect.Effect<
+  void,
+  misc.UpdatePassThroughEndpointsConfigPassThroughEndpointEndpointIdPostError,
+  LitellmOpContext
+> =>
+  mutate(
+    misc
+      .updatePassThroughEndpointsConfigPassThroughEndpointEndpointIdPost({
+        ...body,
+        endpoint_id: endpointId,
+      })
+      .pipe(Effect.asVoid),
+  );
+
+/**
+ * DELETE /config/pass_through_endpoint?endpoint_id=… — idempotent BY THIS FUNCTION, not by the
+ * vendor. ⚠️ Measured at v1.100.0: deleting an id the list does not have raises `HTTPException(400)`
+ * from `pass_through_endpoint_delete`, which the SDK decodes as a typed `BadRequest` — but the SAME
+ * route also raises the SAME `BadRequest` for `not_allowed_access` (a non-PROXY_ADMIN caller) or a
+ * disconnected DB, on a row that never got deleted. A `BadRequest` alone cannot tell the two apart,
+ * so THIS FUNCTION DOESN'T GUESS FROM THE TAG ALONE: on `BadRequest` it re-lists (a GET — no
+ * PROXY_ADMIN required) and only treats the delete as already-done if `endpointId` is genuinely
+ * absent; otherwise the delete failed and this re-fails with the ORIGINAL error, not a message
+ * match (S21 — a status-and-a-real-read decision, never body text).
+ */
+export const deletePassThroughEndpoint = (
+  endpointId: string,
+): Effect.Effect<
+  void,
+  misc.DeletePassThroughEndpointsConfigPassThroughEndpointDeleteError,
+  LitellmOpContext
+> =>
+  mutate(
+    misc
+      .deletePassThroughEndpointsConfigPassThroughEndpointDelete({ endpoint_id: endpointId })
+      .pipe(
+        Effect.asVoid,
+        Effect.catchTag('BadRequest', (original) =>
+          Effect.gen(function* () {
+            const rows = yield* listPassThroughEndpoints();
+            if (rows.some((row) => row.id === endpointId)) return yield* Effect.fail(original);
+          }),
+        ),
+      ),
+  );