@homeflare/alchemy 0.52.0 → 0.53.1

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'),
+  );
+});

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

@@ -0,0 +1,181 @@
+/**
+ * `LiteLLM.ClaudeCodeMarketplacePlugin` through Alchemy's real Plan and Apply over the fake proxy
+ * (`fake-marketplace-litellm.ts`): register, no-op, update, adopt, enable, retain, delete.
+ *
+ * ★ EVERY VALUE IS `FAKE-*`. ⚠️ THE FAKE'S ANSWERS ARE UNMEASURED (its header).
+ */
+import { expect, test } from 'bun:test';
+import { credentials } from '@distilled.cloud/litellm/Credentials';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/http/FetchHttpClient';
+import { LiteLLMClaudeCodeMarketplacePlugin } from './marketplace-plugin.ts';
+import { deletePlugin } from './marketplace-operations.ts';
+import type { MarketplacePluginProps } from './marketplace-types.ts';
+import { FAKE_BASE } from './fake-litellm.ts';
+import {
+  type FakeMarketplaceLitellm,
+  pluginRow,
+  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('registers a plugin, lists it in the marketplace, then a second deploy writes nothing', async () => {
+  const fake = startFakeMarketplaceLitellm();
+  const same = stack(fake);
+  expect(await same.deploy(declare(workflows))).toEqual({ Workflows: 'create' });
+  expect(fake.plugins()[0]).toMatchObject({ enabled: true, name: 'fake-workflows' });
+  expect(await fake.listed()).toEqual(['fake-workflows']);
+  const before = fake.requests().length;
+  expect(await same.deploy(declare(workflows))).toEqual({ Workflows: 'noop' });
+  expect(writesOf(fake.requests().slice(before))).toEqual([]);
+});
+
+test('a plugin the proxy registers disabled is enabled, because the marketplace lists only enabled ones', async () => {
+  const fake = startFakeMarketplaceLitellm({ registerDisabled: true });
+  await stack(fake).deploy(declare(workflows));
+  expect(writesOf(fake.requests())).toContain('POST /claude-code/plugins/fake-workflows/enable');
+  expect(await fake.listed()).toEqual(['fake-workflows']);
+});
+
+test('enabled: false disables a listed plugin through the disable route', async () => {
+  const fake = startFakeMarketplaceLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(workflows));
+  expect(await same.deploy(declare({ ...workflows, enabled: false }))).toEqual({
+    Workflows: 'update',
+  });
+  expect(await fake.listed()).toEqual([]);
+});
+
+test('an update re-sends what the live plugin has, so an undeclared field is not wiped', async () => {
+  const fake = startFakeMarketplaceLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(workflows));
+  const { description: _d, keywords: _k, version: _v, ...withoutOptional } = workflows;
+  const moved = {
+    ...withoutOptional,
+    source: { repo: 'FAKE-org/FAKE-other', source: 'github' },
+  };
+  expect(await same.deploy(declare(moved))).toEqual({ Workflows: 'update' });
+  expect(fake.plugins()[0]).toMatchObject({
+    description: 'FAKE workflows',
+    keywords: ['fake-a', 'fake-b'],
+    source: moved.source,
+    version: '1.0.0',
+  });
+});
+
+test('an update keeps a live author email when the declaration gives only a name', async () => {
+  const fake = startFakeMarketplaceLitellm();
+  const same = stack(fake);
+  const withAuthor = { ...workflows, author: { name: 'FAKE Author', email: 'fake@example.com' } };
+  await same.deploy(declare(withAuthor));
+  const moved = {
+    ...withAuthor,
+    source: { repo: 'FAKE-org/FAKE-other', source: 'github' },
+    author: { name: 'FAKE Author' },
+  };
+  expect(await same.deploy(declare(moved))).toEqual({ Workflows: 'update' });
+  expect(fake.plugins()[0]).toMatchObject({
+    author: { name: 'FAKE Author', email: 'fake@example.com' },
+  });
+});
+
+test('a live plugin is Unowned: refused without --adopt, taken by name with it, writing nothing', async () => {
+  const live = pluginRow({
+    description: 'FAKE workflows',
+    keywords: ['fake-a', 'fake-b'],
+    name: 'fake-workflows',
+    version: '1.0.0',
+  });
+  const fake = startFakeMarketplaceLitellm({ seed: [live] });
+  const engine = stack(fake);
+  await expect(engine.deploy(declare(workflows))).rejects.toThrow();
+  expect(writesOf(fake.requests())).toEqual([]);
+  expect(Object.values(await engine.deploy(declare(workflows), { adopt: true }))).toEqual([
+    'adopted',
+  ]);
+  expect(writesOf(fake.requests())).toEqual([]);
+});
+
+test('a proxy that drops the source on a PUT fails the deploy instead of claiming success', async () => {
+  const fake = startFakeMarketplaceLitellm({ ignoreSource: true });
+  const same = stack(fake);
+  await same.deploy(declare(workflows));
+  await expect(
+    same.deploy(declare({ ...workflows, source: { repo: 'FAKE-org/FAKE-x', source: 'github' } })),
+  ).rejects.toThrow();
+});
+
+test('a write refused for lack of rights fails the deploy and leaves nothing registered', async () => {
+  const fake = startFakeMarketplaceLitellm({ forbidWrites: true });
+  await expect(stack(fake).deploy(declare(workflows))).rejects.toThrow();
+  expect(fake.plugins()).toEqual([]);
+});
+
+test('a refused declaration fails the plan before a single request', async () => {
+  for (const props of [
+    { ...workflows, pluginName: 'Not_Kebab' },
+    { ...workflows, source: {} },
+    { ...workflows, source: { repo: ' ', source: 'github' } },
+    { ...workflows, source: { source: 'arxiv' } },
+    { ...workflows, description: '  ' },
+    { ...workflows, keywords: ['fake-a', 'fake-a'] },
+    { ...workflows, author: { name: ' ' } },
+  ]) {
+    const fake = startFakeMarketplaceLitellm();
+    await expect(stack(fake).deploy(declare(props))).rejects.toThrow();
+    expect(fake.requests()).toEqual([]);
+  }
+});
+
+test('removing the declaration RETAINS the plugin: nothing deletes an install source unless the stack opts in', async () => {
+  const fake = startFakeMarketplaceLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(workflows));
+  await same.deploy(Effect.void);
+  expect(fake.plugins()).toHaveLength(1);
+  expect(writesOf(fake.requests())).not.toContain('DELETE /claude-code/plugins/fake-workflows');
+});
+
+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('delete removes the plugin, and a missing one is swallowed only because a real read says so', async () => {
+  const fake = startFakeMarketplaceLitellm({ seed: [pluginRow({ name: 'fake-workflows' })] });
+  await run(fake.fetch, deletePlugin('fake-workflows'));
+  expect(fake.plugins()).toEqual([]);
+  await run(fake.fetch, deletePlugin('fake-workflows'));
+});
+
+test('a delete refused for lack of rights re-raises the ORIGINAL error and the plugin stays', async () => {
+  const fake = startFakeMarketplaceLitellm({
+    forbidWrites: true,
+    seed: [pluginRow({ name: 'fake-workflows' })],
+  });
+  await expect(run(fake.fetch, deletePlugin('fake-workflows'))).rejects.toThrow();
+  expect(fake.plugins()).toHaveLength(1);
+});

package/src/litellm/marketplace-plugin.ts

@@ -0,0 +1,156 @@
+/**
+ * `LiteLLM.ClaudeCodeMarketplacePlugin` — one plugin registered in LiteLLM's Claude Code marketplace
+ * (`/claude-code/plugins`), which LiteLLM serves as `/claude-code/marketplace.json`. Types and what
+ * is left out: marketplace-types.ts.
+ *
+ * ★ ADOPT BY NAME. `name` is unique, so `pluginName` finds the one live row. A live row with no
+ *   state is `Unowned`, so it needs `--adopt`.
+ * ★ `defaultRemovalPolicy: 'retain'`: deleting a plugin removes the install source every Claude Code
+ *   client has pointed at. Opt in with `.pipe(RemovalPolicy.destroy())`.
+ * ★ A NEW NAME IS A REPLACE: the name is the path key of every call, so there is no rename. Under
+ *   the default `retain` the old plugin stays registered and listed until it is removed by hand or
+ *   the stack opts in with `.pipe(RemovalPolicy.destroy())`.
+ * ★ THE PROOF IS THE MARKETPLACE FILE: after a deploy, `GET /claude-code/marketplace.json` lists the
+ *   plugin only while it is enabled, which is why `enabled` is part of the declaration.
+ * ⛔ NO LITELLM CREDENTIAL IS A PROP; `litellmProviders`' layer supplies `Credentials`.
+ */
+import { Resource } from 'alchemy';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import * as Predicate from 'effect/Predicate';
+import { differing, firstProblem, registerBody, updateBody } from './marketplace-form.ts';
+import {
+  deletePlugin,
+  listPlugins,
+  registerPlugin,
+  setEnabled,
+  updatePlugin,
+} from './marketplace-operations.ts';
+import type { MarketplacePluginAttributes, MarketplacePluginProps } from './marketplace-types.ts';
+import {
+  LitellmRegistryAbsentAfterWriteError,
+  LitellmRegistryNotConvergedError,
+} from './registry-errors.ts';
+import { dieIfInvalid, failIfInvalid } from './registry-support.ts';
+
+export type { MarketplacePluginAttributes, MarketplacePluginProps };
+export type { RegistryError as MarketplacePluginError } from './registry-errors.ts';
+
+const RESOURCE = 'LiteLLM.ClaudeCodeMarketplacePlugin';
+
+export interface LiteLLMClaudeCodeMarketplacePlugin extends Resource<
+  'LiteLLM.ClaudeCodeMarketplacePlugin',
+  MarketplacePluginProps,
+  MarketplacePluginAttributes
+> {}
+
+export const LiteLLMClaudeCodeMarketplacePlugin = Resource<LiteLLMClaudeCodeMarketplacePlugin>(
+  'LiteLLM.ClaudeCodeMarketplacePlugin',
+  { defaultRemovalPolicy: 'retain' },
+);
+
+export const isLiteLLMClaudeCodeMarketplacePlugin = (
+  value: unknown,
+): value is LiteLLMClaudeCodeMarketplacePlugin =>
+  Predicate.hasProperty(value, 'Type') && value.Type === 'LiteLLM.ClaudeCodeMarketplacePlugin';
+
+/** The name is the identity: a recorded name is looked up by that name, state or no state. */
+const locate = (
+  rows: readonly MarketplacePluginAttributes[],
+  props: MarketplacePluginProps,
+  output: MarketplacePluginAttributes | undefined,
+) => rows.find((row) => row.pluginName === (output?.pluginName ?? props.pluginName));
+
+const findNamed = (name: string) =>
+  listPlugins().pipe(Effect.map((rows) => rows.find((row) => row.pluginName === name)));
+
+/** ⛔ TEST-ONLY EXPORT. Not on index.ts's barrel. */
+export const marketplacePluginHandlers = {
+  /** ⛔ With no `output` this is the adoption probe, so the refusals run here too. */
+  read: ({
+    olds,
+    output,
+  }: {
+    olds: MarketplacePluginProps;
+    output: MarketplacePluginAttributes | undefined;
+  }) =>
+    Effect.gen(function* () {
+      if (output === undefined) {
+        yield* dieIfInvalid(RESOURCE, String(olds.pluginName), firstProblem(olds));
+      }
+      const live = locate(yield* listPlugins(), olds, output);
+      if (live === undefined) return undefined;
+      return output === undefined ? Unowned(live) : live;
+    }),
+
+  diff: ({
+    news,
+    output,
+  }: {
+    news: Input<MarketplacePluginProps>;
+    output: MarketplacePluginAttributes | undefined;
+  }) =>
+    Effect.gen(function* () {
+      if (!isResolved(news)) return undefined;
+      yield* failIfInvalid(RESOURCE, String(news.pluginName), firstProblem(news));
+      if (output === undefined) return undefined;
+      if (output.pluginName !== news.pluginName) return { action: 'replace' } as const;
+      return differing(output, news).length === 0
+        ? ({ action: 'noop' } as const)
+        : ({ action: 'update' } as const);
+    }),
+
+  reconcile: ({
+    news,
+    output,
+  }: {
+    news: MarketplacePluginProps;
+    output: MarketplacePluginAttributes | undefined;
+  }) =>
+    Effect.gen(function* () {
+      yield* failIfInvalid(RESOURCE, String(news.pluginName), firstProblem(news));
+      const before = locate(yield* listPlugins(), news, output);
+      // ★ register is create-only and returns 409 if the name exists (`claude_code_marketplace.ts:546`);
+      //   it is issued only after the list showed the name absent. The metadata write and the enable
+      //   switch are separate calls, each issued only when the live row differs.
+      if (before === undefined) yield* registerPlugin(registerBody(news));
+      else if (differing(before, news).some((field) => field !== 'enabled')) {
+        yield* updatePlugin(news.pluginName, updateBody(news, before));
+      }
+      const written = yield* findNamed(news.pluginName);
+      if (written !== undefined && written.enabled !== (news.enabled ?? true)) {
+        yield* setEnabled(news.pluginName, news.enabled ?? true);
+      }
+      const after = yield* findNamed(news.pluginName);
+      if (after === undefined) {
+        return yield* Effect.fail(
+          new LitellmRegistryAbsentAfterWriteError({ name: news.pluginName, resource: RESOURCE }),
+        );
+      }
+      const left = differing(after, news);
+      if (left.length > 0) {
+        return yield* Effect.fail(
+          new LitellmRegistryNotConvergedError({
+            fields: left,
+            name: news.pluginName,
+            resource: RESOURCE,
+          }),
+        );
+      }
+      return after;
+    }),
+
+  delete: ({ output }: { output: MarketplacePluginAttributes }) => deletePlugin(output.pluginName),
+
+  /** ⛔ EMPTY: adoption is an explicit act (`--adopt`), and no ownership mark exists to filter by. */
+  list: () => Effect.succeed([]),
+};
+
+export const LiteLLMClaudeCodeMarketplacePluginProvider = () =>
+  Provider.effect(
+    LiteLLMClaudeCodeMarketplacePlugin,
+    Effect.succeed(LiteLLMClaudeCodeMarketplacePlugin.Provider.of(marketplacePluginHandlers)),
+  );