@homeflare/alchemy 0.51.0 → 0.53.0

package/src/linux/container-form.ts

@@ -16,6 +16,15 @@
  *   `containerProblems` below. A container that needs a secret takes `EnvironmentFile=` pointing at
  *   a host path an out-of-band secret renderer (openbao-agent) maintains; this family never reads
  *   or renders that file's contents.
+ * ⛔ `Environment=` VALUES ARE ALWAYS QUOTED, VIA container-env-quote.ts — measured 2026-10-11:
+ *   unquoted, a spaced value splits at its first space, a quoted fragment re-parses into a bogus
+ *   variable, and an unknown C escape drops the line's assignments silently (ice2/grafana-oidc.md;
+ *   the live podman 5.4.2 generator reproduced all three). Quoting costs the PARSE nothing — the
+ *   generator reads a quoted line as exactly one assignment — and it also stops systemd expanding
+ *   `%` specifiers in values. It is NOT free at deploy: every Environment line's BYTES change, so
+ *   the first deploy after this bump rewrites the file and RESTARTS every container declaring
+ *   `environment` (all 13 on ct100; only grafana's values change meaning) — plan it as one window.
+ *   Newlines are refused, never encoded (same module).
  * ⛔ `[Install]` SUPPORTS ONLY `Alias=`/`WantedBy=`/`RequiredBy=` FOR A `.container` FILE (same doc,
  *   "Currently, only the Alias, WantedBy and RequiredBy keys are supported") — NOT `Also=`, which
  *   plain `systemd.unit(5)` allows and unit-text.ts's `INSTALL_KEYS` therefore lists. See
@@ -23,9 +32,14 @@
  */
 import { type UnitSection, configDigest, digestOf, renderUnit } from './unit-form.ts';
 import { podmanArgsProblems, secretLikeEnvironment, secretLikeLines } from './container-secrets.ts';
+import { environmentLines, environmentValueProblems } from './container-env-quote.ts';
+import { QUADLET_DEFAULT_DIRECTORY, QUADLET_SEARCH_DIRECTORIES } from './container-paths.ts';
 
 /** ★ Reused, not redefined: same digest and `restartOn`-join contract as Systemd.Unit. */
 export { configDigest, digestOf };
+// ★ The search path lives in container-paths.ts (file-length cap) and is re-exported here so every
+//   importer and the barrel keep one import site — the API does not move.
+export { QUADLET_DEFAULT_DIRECTORY, QUADLET_SEARCH_DIRECTORIES };
 
 export type UnitLine = readonly [key: string, value: string];
 
@@ -64,7 +78,8 @@ export type ContainerSection = {
 export type ContainerProps = {
   /** The Quadlet file's basename, WITHOUT `.container`. Written as `<name>.container`. */
   name: string;
-  /** @default QUADLET_DEFAULT_DIRECTORY. Must be one of QUADLET_SEARCH_DIRECTORIES (below). */
+  /** @default QUADLET_DEFAULT_DIRECTORY. Must be one of QUADLET_SEARCH_DIRECTORIES
+   *  (container-paths.ts, where the search path now lives). */
   directory?: string;
   /** `[Unit]` — `Description=`/`Documentation=` typed, everything else verbatim (see file header). */
   unit?: { description?: string; documentation?: string; lines?: readonly UnitLine[] };
@@ -103,25 +118,8 @@ export type ContainerAttributes = {
 };
 
 /**
- * Podman's OWN rootful search path, most specific first — `podman-systemd.unit(5)`, "Podman Unit
- * Search Path", Podman 5.4, read 2026-09-24: "Quadlet files for the root user can be placed in the
- * following directories ordered in precedence" (`/run` over `/etc` over `/usr/share`).
- * ★ CT100's `caddy.container` lives in the middle one — measured live, `cat` over `ssh ct100`,
- *   2026-09-24: `/etc/containers/systemd/caddy.container`.
- * ⛔ A directory outside this list is invisible to Quadlet: the generator only reads these three, so
- *   a file elsewhere is a `.container` file with no `.service` ever generated from it — silently,
- *   unlike `Systemd.Unit`'s directory check, which at least writes a unit systemd could load if only
- *   it were enabled. See `containerProblems`.
+ * ★ A conservative subset of what Quadlet itself accepts as a unit name: no template `@`, no `/`.
  */
-export const QUADLET_SEARCH_DIRECTORIES = [
-  '/run/containers/systemd',
-  '/etc/containers/systemd',
-  '/usr/share/containers/systemd',
-] as const;
-
-export const QUADLET_DEFAULT_DIRECTORY = '/etc/containers/systemd';
-
-/** ★ A conservative subset of what Quadlet itself accepts as a unit name: no template `@`, no `/`. */
 export const NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
 
 export const containerPathFor = (props: Pick<ContainerProps, 'name' | 'directory'>): string =>
@@ -149,13 +147,8 @@ const containerLines = (c: ContainerSection): UnitLine[] => [
   ...(c.exec === undefined ? [] : [['Exec', c.exec] as UnitLine]),
   ...(c.autoUpdate === undefined ? [] : [['AutoUpdate', c.autoUpdate] as UnitLine]),
   ...(c.environmentFile ?? []).map((file): UnitLine => ['EnvironmentFile', file]),
-  // ★ Sorted by key: a stable render for a plain object whose own key order JS does not promise.
-  ...Object.keys(c.environment ?? {})
-    .sort()
-    .map((key): UnitLine => [
-      'Environment',
-      `${key}=${(c.environment as Record<string, string>)[key]}`,
-    ]),
+  // ⛔ Always quoted, via container-env-quote.ts (see this file's header) — sorted there too.
+  ...environmentLines(c.environment ?? {}),
   ...(c.volume ?? []).map((volume): UnitLine => ['Volume', volume]),
   ...(c.publishPort ?? []).map((port): UnitLine => ['PublishPort', port]),
   ...(c.podmanArgs ?? []).map((arg): UnitLine => ['PodmanArgs', arg]),
@@ -225,19 +218,30 @@ export const containerProblems = (props: ContainerProps): string[] => {
       (problem) => `container.${problem}`,
     ),
   );
+  // ⛔ Newlines in a key or value are refused before anything renders: a .container file is read
+  //   line by line, so a raw newline ends the assignment mid-value and whatever follows parses as a
+  //   NEW directive (key injection when a value comes from external config). Strings here so one
+  //   plan shows every refusal at once; the typed error stays the contract for direct renderers.
+  const envProblems = environmentValueProblems(props.container.environment ?? {});
+  found.push(...envProblems);
   // ★ Every OTHER rendered line — `Exec=`/`PodmanArgs=` and the `unit`/`service`/`install` escape
   //   hatches — checked too, so a secret cannot reach the file through a field this typed check does
   //   not otherwise inspect. `container.environment`'s OWN lines are excluded: `secretLikeEnvironment`
   //   above already checked them, with a better error message (the actual env var name).
+  //   ⛔ The sweep renders WITHOUT the environment (a newline value cannot throw here); the NUL
+  //   check is skipped when the environment could not render — the refusals above are its result.
+  const { environment: _env, ...withoutEnvironment } = props.container;
   found.push(
     ...secretLikeLines([
       ...unitLines(props),
-      ...containerLines(props.container).filter(([key]) => key !== 'Environment'),
+      // ⛔ No `Environment` filter needed: the destructure above removed the only field whose
+      //   lines would carry it, so `containerLines` here emits none — a filter would be dead code.
+      ...containerLines(withoutEnvironment),
       ...serviceLines(props),
       ...installLines(props),
     ]),
   );
-  if (renderContainerFile(props).includes('\u0000'))
+  if (envProblems.length === 0 && renderContainerFile(props).includes('\u0000'))
     found.push('the rendered .container file contains NUL');
   return found;
 };

package/src/linux/container-paths.ts

@@ -0,0 +1,21 @@
+/**
+ * Where Quadlet looks for `.container` files — split out of container-form.ts under the file-length
+ * cap, with the measured context that justifies every entry kept intact.
+ *
+ * Podman's OWN rootful search path, most specific first — `podman-systemd.unit(5)`, "Podman Unit
+ * Search Path", Podman 5.4, read 2026-09-24: "Quadlet files for the root user can be placed in the
+ * following directories ordered in precedence" (`/run` over `/etc` over `/usr/share`).
+ * ★ CT100's `caddy.container` lives in the middle one — measured live, `cat` over `ssh ct100`,
+ *   2026-09-24: `/etc/containers/systemd/caddy.container`.
+ * ⛔ A directory outside this list is invisible to Quadlet: the generator only reads these three, so
+ *   a file elsewhere is a `.container` file with no `.service` ever generated from it — silently,
+ *   unlike `Systemd.Unit`'s directory check, which at least writes a unit systemd could load if only
+ *   it were enabled. See `containerProblems`.
+ */
+export const QUADLET_SEARCH_DIRECTORIES = [
+  '/run/containers/systemd',
+  '/etc/containers/systemd',
+  '/usr/share/containers/systemd',
+] as const;
+
+export const QUADLET_DEFAULT_DIRECTORY = '/etc/containers/systemd';

package/src/litellm/fake-marketplace-litellm.test.ts

@@ -0,0 +1,51 @@
+/**
+ * Fake-level assertions for `fake-marketplace-litellm.ts` against the distilled 1.103.0 route docs.
+ */
+import { expect, test } from 'bun:test';
+import { credentials } from '@distilled.cloud/litellm/Credentials';
+import * as Effect from 'effect/Effect';
+import * as FetchHttpClient from 'effect/http/FetchHttpClient';
+import * as Layer from 'effect/Layer';
+import { registerPlugin, updatePlugin } from './marketplace-operations.ts';
+import { FAKE_BASE } from './fake-litellm.ts';
+import { pluginRow, startFakeMarketplaceLitellm } from './fake-marketplace-litellm.ts';
+import { FAKE_KEY } from './fake-registry-base.ts';
+
+const run = <A, E>(fetchFn: typeof globalThis.fetch, effect: Effect.Effect<A, E, unknown>) =>
+  Effect.runPromise(
+    effect.pipe(
+      Effect.provide(FetchHttpClient.layer),
+      Effect.provide(Layer.succeed(FetchHttpClient.Fetch, fetchFn)),
+      Effect.provide(credentials({ apiKey: FAKE_KEY, baseUrl: FAKE_BASE })),
+    ) as Effect.Effect<A, E, never>,
+  );
+
+test('register is create-only: a second POST of the same name returns 409 and changes nothing', async () => {
+  const fake = startFakeMarketplaceLitellm();
+  await run(fake.fetch, registerPlugin({ name: 'fake-workflows', source: { source: 'github' } }));
+  const before = fake.plugins()[0];
+  await expect(
+    run(fake.fetch, registerPlugin({ name: 'fake-workflows', source: { source: 'github' } })),
+  ).rejects.toThrow();
+  expect(fake.plugins()).toHaveLength(1);
+  expect(fake.plugins()[0]).toEqual(before);
+});
+
+test('PUT is a full replace: an omitted description is reset to null', async () => {
+  const fake = startFakeMarketplaceLitellm({
+    seed: [
+      pluginRow({
+        description: 'FAKE workflows',
+        name: 'fake-workflows',
+        source: { source: 'github', repo: 'FAKE-org/FAKE-repo' },
+      }),
+    ],
+  });
+  await run(
+    fake.fetch,
+    updatePlugin('fake-workflows', {
+      source: { source: 'github', repo: 'FAKE-org/FAKE-repo' },
+    }),
+  );
+  expect(fake.plugins()[0]).toMatchObject({ description: null, name: 'fake-workflows' });
+});

package/src/litellm/fake-marketplace-litellm.ts

@@ -0,0 +1,134 @@
+/**
+ * A fake of LiteLLM's `/claude-code/*` routes for tests — TEST ONLY. Skeleton and the rules every
+ * fake follows: fake-registry-base.ts.
+ *
+ * ★ MEASURED AGAINST THE GENERATED 1.103.0 ROUTE DOCS:
+ *   - `POST /claude-code/plugins` is create-only and never overwrites; if `name` already exists it
+ *     returns 409 Conflict (`claude_code_marketplace.ts:546`).
+ *   - `PUT /claude-code/plugins/{name}` is a full replace, not a merge: any optional field left out
+ *     is reset to its default (`claude_code_marketplace.ts:563`).
+ *   - `PluginListItem` optional fields: author, category, description, domain, homepage, keywords,
+ *     namespace, version (`claude_code_marketplace.ts:211-226`).
+ *   - Enable/disable flip `enabled`; `GET /claude-code/marketplace.json` lists only enabled plugins.
+ *   - Writes need an admin key (`forbidWrites` models the 403).
+ *   - `registerDisabled` models a proxy whose register leaves the plugin disabled, which the resource
+ *     must not trust. `ignoreSource` models a PUT that drops the source field.
+ * ⚠️ EVERY OTHER ANSWER IS UNMEASURED; shapes come from the generated 1.103.0 schema.
+ */
+import { FAKE_KEY, type FakeRecord, json, recordingFetch } from './fake-registry-base.ts';
+import type { Row } from './registry-support.ts';
+
+export interface FakeMarketplaceLitellm extends FakeRecord {
+  readonly plugins: () => readonly Row[];
+  /** The names `GET /claude-code/marketplace.json` lists right now. */
+  readonly listed: () => Promise<readonly string[]>;
+}
+
+export interface FakeMarketplaceOptions {
+  readonly seed?: readonly Row[];
+  readonly forbidWrites?: boolean;
+  readonly registerDisabled?: boolean;
+  readonly ignoreSource?: boolean;
+}
+
+export const pluginRow = (fields: Row): Row => ({
+  created_at: '2026-10-12T00:00:00Z',
+  description: null,
+  enabled: true,
+  id: `FAKE-plugin-${String(fields['name'])}`,
+  source: { repo: 'FAKE-org/FAKE-repo', source: 'github' },
+  updated_at: '2026-10-12T00:00:00Z',
+  version: null,
+  ...fields,
+});
+
+const OPTIONAL_PUT_FIELDS = [
+  'author',
+  'category',
+  'description',
+  'domain',
+  'homepage',
+  'keywords',
+  'namespace',
+  'version',
+] as const;
+
+export const startFakeMarketplaceLitellm = (
+  options: FakeMarketplaceOptions = {},
+): FakeMarketplaceLitellm => {
+  let rows: Row[] = (options.seed ?? []).map((row) => ({ ...row }));
+
+  const record = recordingFetch(FAKE_KEY, ({ body, request, url }) => {
+    const byName = /^\/claude-code\/plugins\/([^/]+)(\/enable|\/disable)?$/.exec(url.pathname);
+    if (url.pathname === '/claude-code/plugins' && request.method === 'GET') {
+      return json(200, { count: rows.length, plugins: rows });
+    }
+    if (url.pathname === '/claude-code/marketplace.json' && request.method === 'GET') {
+      return json(200, {
+        name: 'FAKE-litellm',
+        plugins: rows
+          .filter((row) => row['enabled'] === true)
+          .map((row) => ({ name: row['name'] })),
+      });
+    }
+    if (request.method !== 'GET' && options.forbidWrites === true) {
+      return json(403, { detail: { error: 'not_allowed_access' } });
+    }
+    if (url.pathname === '/claude-code/plugins' && request.method === 'POST') {
+      const name = body['name'];
+      if (rows.some((row) => row['name'] === name)) {
+        return json(409, { detail: `Plugin '${name}' already exists` });
+      }
+      const next = pluginRow({
+        ...body,
+        enabled: options.registerDisabled !== true,
+      });
+      rows = [...rows, next];
+      return json(200, { action: 'created', plugin: next, status: 'success' });
+    }
+    if (byName !== null) {
+      const name = decodeURIComponent(byName[1] ?? '');
+      const at = rows.findIndex((row) => row['name'] === name);
+      if (at === -1) return json(404, { detail: `Plugin '${name}' not found` });
+      const row = rows[at];
+      if (row === undefined) return json(404, { detail: `Plugin '${name}' not found` });
+      if (request.method === 'PUT') {
+        const reset = Object.fromEntries(
+          OPTIONAL_PUT_FIELDS.map((field) => [field, body[field] ?? null]),
+        );
+        const source = options.ignoreSource === true ? row['source'] : body['source'];
+        const next = pluginRow({
+          ...row,
+          ...reset,
+          source,
+        });
+        rows = rows.map((each, i) => (i === at ? next : each));
+        return json(200, { action: 'updated', plugin: next, status: 'success' });
+      }
+      if (request.method === 'POST' && byName[2] !== undefined) {
+        rows = rows.map((each, i) =>
+          i === at ? { ...each, enabled: byName[2] === '/enable' } : each,
+        );
+        return json(200, { status: 'success' });
+      }
+      if (request.method === 'DELETE') {
+        rows = rows.filter((_, i) => i !== at);
+        return json(200, { status: 'success' });
+      }
+    }
+    return json(404, { detail: 'not found' });
+  });
+
+  return {
+    ...record,
+    listed: async () => {
+      const response = await record.fetch('http://fake.local/claude-code/marketplace.json', {
+        headers: { authorization: `Bearer ${FAKE_KEY}` },
+        method: 'GET',
+      });
+      const payload = (await response.json()) as { plugins?: readonly { name?: unknown }[] };
+      return (payload.plugins ?? []).map((each) => String(each.name));
+    },
+    plugins: () => rows.map((row) => ({ ...row })),
+  };
+};

package/src/litellm/index.ts

@@ -79,6 +79,14 @@ export {
   type AccessGroupError,
   type AccessGroupProps,
 } from './access-group.ts';
+export {
+  LiteLLMClaudeCodeMarketplacePlugin,
+  LiteLLMClaudeCodeMarketplacePluginProvider,
+  isLiteLLMClaudeCodeMarketplacePlugin,
+  type MarketplacePluginAttributes,
+  type MarketplacePluginError,
+  type MarketplacePluginProps,
+} from './marketplace-plugin.ts';
 export {
   LiteLLMPolicyAttachment,
   LiteLLMPolicyAttachmentProvider,

package/src/litellm/marketplace-form.ts

@@ -0,0 +1,160 @@
+/**
+ * Wire bodies, comparison and refusals for `LiteLLM.ClaudeCodeMarketplacePlugin`.
+ *
+ * ★ THE UPDATE IS A FULL PUT: `source` is required and `version` is "cleared if omitted"
+ *   (`claude_code_marketplace.ts:563`), so an update carries every optional field the plugin
+ *   already has; a field the declaration leaves out is re-sent as it is live, never wiped.
+ * ★ REGISTER IS CREATE-ONLY: `POST /claude-code/plugins` returns 409 if the name already exists
+ *   (`claude_code_marketplace.ts:546`), so `reconcile` registers only after a list shows the name
+ *   absent.
+ */
+import type * as cc from '@distilled.cloud/litellm/claude_code_marketplace';
+import {
+  asRow,
+  canonical,
+  firstBadEntry,
+  firstDuplicate,
+  isBlank,
+  sameSet,
+  stringOrNull,
+  stringsOf,
+} from './registry-support.ts';
+import type { MarketplacePluginAttributes, MarketplacePluginProps } from './marketplace-types.ts';
+
+const TEXT = ['description', 'version', 'domain', 'namespace', 'category', 'homepage'] as const;
+
+const SOURCE_KINDS = new Set(['github', 'url', 'git-subdir', 'archive']);
+
+/** The first reason a declaration is refused, or `undefined`. Runs before any request. */
+export const firstProblem = (props: MarketplacePluginProps): string | undefined => {
+  if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(String(props.pluginName))) {
+    return '`pluginName` must be kebab-case (lowercase letters, digits and single hyphens)';
+  }
+  const source = props.source as Readonly<Record<string, unknown>> | undefined;
+  if (source === undefined || isBlank(source['source'])) {
+    return '`source` needs a `source` kind (github, url, git-subdir or archive)';
+  }
+  if (!SOURCE_KINDS.has(String(source['source']))) {
+    return `\`source.source\` must be github, url, git-subdir or archive`;
+  }
+  for (const [key, value] of Object.entries(source)) {
+    if (isBlank(key) || isBlank(value)) return `\`source.${key}\` is blank`;
+  }
+  for (const field of TEXT) {
+    if (props[field] !== undefined && isBlank(props[field])) {
+      return `\`${field}\` is blank; leave it out to keep the live text`;
+    }
+  }
+  if (props.author !== undefined && isBlank(props.author.name)) return '`author.name` is blank';
+  const bad = firstBadEntry(props.keywords ?? []);
+  if (bad !== undefined) return `\`keywords\` has a blank or padded entry (${JSON.stringify(bad)})`;
+  const twice = firstDuplicate(props.keywords ?? []);
+  if (twice !== undefined) return `\`keywords\` lists ${JSON.stringify(twice)} twice`;
+  return undefined;
+};
+
+const sourceOf = (value: unknown): Readonly<Record<string, string>> =>
+  Object.fromEntries(
+    Object.entries(asRow(value) ?? {}).filter(
+      (entry): entry is [string, string] => typeof entry[1] === 'string',
+    ),
+  );
+
+/** One list item. `undefined` is "not a plugin row": the caller refuses the whole answer. */
+export const toAttributes = (value: unknown): MarketplacePluginAttributes | undefined => {
+  const row = asRow(value);
+  if (row === undefined) return undefined;
+  const pluginId = row['id'];
+  const pluginName = row['name'];
+  if (typeof pluginId !== 'string' || typeof pluginName !== 'string') return undefined;
+  const author = asRow(row['author']);
+  return {
+    author:
+      author !== undefined && typeof author['name'] === 'string'
+        ? { email: stringOrNull(author['email']), name: author['name'] }
+        : null,
+    category: stringOrNull(row['category']),
+    description: stringOrNull(row['description']),
+    domain: stringOrNull(row['domain']),
+    enabled: row['enabled'] === true,
+    homepage: stringOrNull(row['homepage']),
+    keywords: canonical(stringsOf(row['keywords'])),
+    namespace: stringOrNull(row['namespace']),
+    pluginId,
+    pluginName,
+    source: sourceOf(row['source']),
+    version: stringOrNull(row['version']),
+  };
+};
+
+const sameSource = (
+  left: Readonly<Record<string, string>>,
+  right: Readonly<Record<string, string>>,
+): boolean => {
+  const a = Object.entries(left).sort(([x], [y]) => x.localeCompare(y));
+  const b = Object.entries(right).sort(([x], [y]) => x.localeCompare(y));
+  return a.length === b.length && a.every(([k, v], i) => k === b[i]?.[0] && v === b[i]?.[1]);
+};
+
+/** Wire names where live and declared disagree. Optional fields count only when declared. */
+export const differing = (
+  live: MarketplacePluginAttributes,
+  props: MarketplacePluginProps,
+): readonly string[] => {
+  const fields: string[] = [];
+  if (!sameSource(live.source, props.source)) fields.push('source');
+  for (const field of TEXT) {
+    if (props[field] !== undefined && live[field] !== props[field]) fields.push(field);
+  }
+  if (props.keywords !== undefined && !sameSet(live.keywords, props.keywords)) {
+    fields.push('keywords');
+  }
+  if (props.author !== undefined) {
+    const same =
+      live.author?.name === props.author.name &&
+      (props.author.email === undefined || live.author.email === props.author.email);
+    if (!same) fields.push('author');
+  }
+  if (live.enabled !== (props.enabled ?? true)) fields.push('enabled');
+  return fields;
+};
+
+/** The metadata both writes share. `live` is the row an update must not wipe. */
+const metadata = (props: MarketplacePluginProps, live?: MarketplacePluginAttributes) => {
+  const author: { name: string; email?: string } | undefined = props.author
+    ? { name: props.author.name }
+    : live?.author
+      ? { name: live.author.name }
+      : undefined;
+  if (author !== undefined) {
+    const keep = props.author?.email ?? live?.author?.email;
+    if (keep !== undefined && keep !== null) {
+      author.email = keep;
+    }
+  }
+  const keywords = props.keywords ?? (live?.keywords.length ? live.keywords : undefined);
+  return {
+    ...(author === undefined ? {} : { author }),
+    ...Object.fromEntries(
+      TEXT.flatMap((field) => {
+        const value = props[field] ?? live?.[field] ?? undefined;
+        return value === undefined ? [] : [[field, value]];
+      }),
+    ),
+    ...(keywords === undefined ? {} : { keywords: [...keywords] }),
+    source: { ...props.source },
+  };
+};
+
+export const registerBody = (
+  props: MarketplacePluginProps,
+): cc.RegisterPluginClaudeCodePluginsPostRequest => ({
+  ...metadata(props),
+  name: props.pluginName,
+});
+
+export const updateBody = (
+  props: MarketplacePluginProps,
+  live: MarketplacePluginAttributes,
+): Omit<cc.UpdatePluginClaudeCodePluginsPluginNamePutRequest, 'plugin_name'> =>
+  metadata(props, live);

package/src/litellm/marketplace-operations.ts

@@ -0,0 +1,76 @@
+/**
+ * The LiteLLM `/claude-code/plugins*` calls `LiteLLM.ClaudeCodeMarketplacePlugin` uses, through
+ * `@distilled.cloud/litellm/claude_code_marketplace` (1.103.0):
+ *
+ *   list     `listPluginsClaudeCodePluginsGet`                      GET    /claude-code/plugins
+ *   register `registerPluginClaudeCodePluginsPost`                  POST   /claude-code/plugins
+ *   update   `updatePluginClaudeCodePluginsPluginNamePut`           PUT    /claude-code/plugins/{name}
+ *   enable   `enablePluginClaudeCodePluginsPluginNameEnablePost`    POST   …/{name}/enable
+ *   disable  `disablePluginClaudeCodePluginsPluginNameDisablePost`  POST   …/{name}/disable
+ *   delete   `deletePluginClaudeCodePluginsPluginNameDelete`        DELETE /claude-code/plugins/{name}
+ *
+ * ⛔ WRITES NEED A PROXY ADMIN KEY. ⛔ NO MESSAGE SNIFFING: the by-name GET is not used, the list
+ *   decides absence (registry-support.ts says why). ★ DELETE IS IDEMPOTENT BY A REAL READ: a failed
+ *   DELETE is swallowed only when the list no longer has the name; otherwise the ORIGINAL error rises.
+ */
+import * as cc from '@distilled.cloud/litellm/claude_code_marketplace';
+import * as Effect from 'effect/Effect';
+import { type LitellmOpContext, throughFetch } from './operations.ts';
+import { LitellmRegistryUnreadableError } from './registry-errors.ts';
+import { asRow, bodyOf } from './registry-support.ts';
+import type { MarketplacePluginAttributes } from './marketplace-types.ts';
+import { toAttributes } from './marketplace-form.ts';
+
+const RESOURCE = 'LiteLLM.ClaudeCodeMarketplacePlugin';
+
+/** Every plugin, enabled or not (`enabled_only` unset). */
+export const listPlugins = (): Effect.Effect<
+  readonly MarketplacePluginAttributes[],
+  cc.ListPluginsClaudeCodePluginsGetError | LitellmRegistryUnreadableError,
+  LitellmOpContext
+> =>
+  throughFetch(cc.listPluginsClaudeCodePluginsGet({})).pipe(
+    Effect.flatMap((response) => {
+      const items = asRow(bodyOf(response))?.['plugins'];
+      const parsed = Array.isArray(items) ? items.map(toAttributes) : undefined;
+      return parsed !== undefined && parsed.every((row) => row !== undefined)
+        ? Effect.succeed(parsed as readonly MarketplacePluginAttributes[])
+        : Effect.fail(
+            new LitellmRegistryUnreadableError({
+              reason: 'no plugins array of rows with an id and a name',
+              resource: RESOURCE,
+            }),
+          );
+    }),
+  );
+
+export const registerPlugin = (body: cc.RegisterPluginClaudeCodePluginsPostRequest) =>
+  throughFetch(cc.registerPluginClaudeCodePluginsPost(body)).pipe(Effect.asVoid);
+
+export const updatePlugin = (
+  name: string,
+  body: Omit<cc.UpdatePluginClaudeCodePluginsPluginNamePutRequest, 'plugin_name'>,
+) =>
+  throughFetch(cc.updatePluginClaudeCodePluginsPluginNamePut({ ...body, plugin_name: name })).pipe(
+    Effect.asVoid,
+  );
+
+export const setEnabled = (name: string, enabled: boolean) =>
+  throughFetch(
+    enabled
+      ? cc.enablePluginClaudeCodePluginsPluginNameEnablePost({ plugin_name: name })
+      : cc.disablePluginClaudeCodePluginsPluginNameDisablePost({ plugin_name: name }),
+  ).pipe(Effect.asVoid);
+
+export const deletePlugin = (name: string) =>
+  throughFetch(cc.deletePluginClaudeCodePluginsPluginNameDelete({ plugin_name: name })).pipe(
+    Effect.asVoid,
+    Effect.catch((original) =>
+      listPlugins().pipe(
+        Effect.catch(() => Effect.fail(original)),
+        Effect.flatMap((rows) =>
+          rows.some((row) => row.pluginName === name) ? Effect.fail(original) : Effect.void,
+        ),
+      ),
+    ),
+  );

package/src/litellm/marketplace-plugin-replace.test.ts

@@ -0,0 +1,68 @@
+/**
+ * `LiteLLM.ClaudeCodeMarketplacePlugin`'s `replace` when `pluginName` changes, through Alchemy's
+ * own Plan and Apply (fake-stack.ts): a rename is create-first under the default `retain`, and
+ * the old name is deleted only under `.pipe(RemovalPolicy.destroy())`.
+ */
+import { expect, test } from 'bun:test';
+import * as RemovalPolicy from 'alchemy/RemovalPolicy';
+import * as Effect from 'effect/Effect';
+import { LiteLLMClaudeCodeMarketplacePlugin } from './marketplace-plugin.ts';
+import type { MarketplacePluginProps } from './marketplace-types.ts';
+import { FAKE_BASE } from './fake-litellm.ts';
+import {
+  type FakeMarketplaceLitellm,
+  startFakeMarketplaceLitellm,
+} from './fake-marketplace-litellm.ts';
+import { FAKE_KEY } from './fake-registry-base.ts';
+import { fakeStack, writesOf } from './fake-stack.ts';
+
+const stack = (fake: FakeMarketplaceLitellm) =>
+  fakeStack({ apiKey: FAKE_KEY, baseUrl: FAKE_BASE }, fake.fetch);
+
+const declare = (props: MarketplacePluginProps, name = 'Workflows') =>
+  Effect.gen(function* () {
+    yield* LiteLLMClaudeCodeMarketplacePlugin(name, props);
+  });
+
+const workflows: MarketplacePluginProps = {
+  description: 'FAKE workflows',
+  keywords: ['fake-a', 'fake-b'],
+  pluginName: 'fake-workflows',
+  source: { repo: 'FAKE-org/FAKE-repo', source: 'github' },
+  version: '1.0.0',
+};
+
+test('a changed pluginName plans replace and leaves the old plugin live under retain', async () => {
+  const fake = startFakeMarketplaceLitellm();
+  const same = stack(fake);
+  expect(await same.deploy(declare(workflows))).toEqual({ Workflows: 'create' });
+
+  const before = fake.requests().length;
+  const renamed = { ...workflows, pluginName: 'fake-other' };
+  expect(await same.deploy(declare(renamed))).toEqual({ Workflows: 'replace' });
+
+  expect(fake.plugins().map((row) => row['name'])).toContain('fake-workflows');
+  expect(fake.plugins().map((row) => row['name'])).toContain('fake-other');
+  expect(writesOf(fake.requests().slice(before))).not.toContain(
+    'DELETE /claude-code/plugins/fake-workflows',
+  );
+});
+
+test('under RemovalPolicy.destroy() a replace creates the new plugin, then deletes the old one', async () => {
+  const fake = startFakeMarketplaceLitellm();
+  const same = stack(fake);
+  const destroy = (props: MarketplacePluginProps) =>
+    Effect.gen(function* () {
+      yield* LiteLLMClaudeCodeMarketplacePlugin('Workflows', props).pipe(RemovalPolicy.destroy());
+    });
+
+  await same.deploy(destroy(workflows));
+  const before = fake.requests().length;
+  await same.deploy(destroy({ ...workflows, pluginName: 'fake-other' }));
+  const writes = writesOf(fake.requests().slice(before));
+
+  expect(fake.plugins().map((row) => row['name'])).toEqual(['fake-other']);
+  expect(writes.indexOf('POST /claude-code/plugins')).toBeLessThan(
+    writes.indexOf('DELETE /claude-code/plugins/fake-workflows'),
+  );
+});