@homeflare/alchemy 0.52.0 → 0.53.0

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

package/src/litellm/marketplace-types.ts

@@ -0,0 +1,53 @@
+/**
+ * What a `LiteLLM.ClaudeCodeMarketplacePlugin` declares (props) and remembers (attributes).
+ *
+ * ★ A PLUGIN IS A MARKETPLACE ENTRY, NOT A SKILL. LiteLLM serves `/claude-code/marketplace.json`
+ *   from the plugins registered under `/claude-code/plugins`; Claude Code installs from that
+ *   marketplace. The plugin folders a seat loads stay what they are (Tim, 2026-10-01); this entry
+ *   points the marketplace at the same folder through `source`.
+ * ★ THE NAME IS THE IDENTITY. `name` is the path key of every read, update and delete, so it cannot
+ *   be renamed in place: changing `pluginName` is a replace, never an update.
+ * ⚠️ `enabled` DEFAULTS TO `true`. A registered but disabled plugin is absent from the marketplace
+ *   file, so a declaration that means "listed" must also mean "enabled".
+ */
+export interface PluginAuthor {
+  readonly name: string;
+  readonly email?: string;
+}
+
+export interface MarketplacePluginProps {
+  /** kebab-case plugin name, e.g. `homeflare-workflows`. Also the way an existing row is adopted. */
+  readonly pluginName: string;
+  /**
+   * Where Claude Code fetches the plugin from, as LiteLLM takes it: `{ source: 'github', repo }`,
+   * `{ source: 'url', url }`, `{ source: 'git-subdir', url, path }` or `{ source: 'archive', url, sha256? }`.
+   * Always compared.
+   */
+  readonly source: Readonly<Record<string, string>>;
+  /** Compared only when declared: adopting never clears text a person wrote. */
+  readonly description?: string;
+  readonly version?: string;
+  readonly domain?: string;
+  readonly namespace?: string;
+  readonly category?: string;
+  readonly homepage?: string;
+  readonly keywords?: readonly string[];
+  readonly author?: PluginAuthor;
+  /** Whether the marketplace lists it. Default `true`. */
+  readonly enabled?: boolean;
+}
+
+export interface MarketplacePluginAttributes {
+  readonly pluginId: string;
+  readonly pluginName: string;
+  readonly source: Readonly<Record<string, string>>;
+  readonly enabled: boolean;
+  readonly description: string | null;
+  readonly version: string | null;
+  readonly domain: string | null;
+  readonly namespace: string | null;
+  readonly category: string | null;
+  readonly homepage: string | null;
+  readonly keywords: readonly string[];
+  readonly author: { readonly name: string; readonly email: string | null } | null;
+}

package/src/litellm/providers.ts

@@ -22,6 +22,7 @@ import { type Credentials, CredentialsFromEnv } from '@distilled.cloud/litellm/C
 import * as Layer from 'effect/Layer';
 import { LiteLLMAccessGroupProvider } from './access-group.ts';
 import { LiteLLMBudgetProvider } from './budget.ts';
+import { LiteLLMClaudeCodeMarketplacePluginProvider } from './marketplace-plugin.ts';
 import { LiteLLMCredentialProvider } from './credential.ts';
 import { LiteLLMMCPServerProvider } from './mcp-server.ts';
 import { LiteLLMKeyProvider } from './key.ts';
@@ -40,6 +41,7 @@ export const litellmProviders = (creds: Layer.Layer<Credentials> = CredentialsFr
     LiteLLMCredentialProvider(),
     LiteLLMMCPServerProvider(),
     LiteLLMAccessGroupProvider(),
+    LiteLLMClaudeCodeMarketplacePluginProvider(),
     LiteLLMToolsetProvider(),
     LiteLLMToolPolicyProvider(),
     LiteLLMPolicyProvider(),

package/src/litellm/registry-exports.test.ts

@@ -14,6 +14,12 @@ const RESOURCES = [
     'LiteLLM.AccessGroup',
     'LiteLLMAccessGroupProvider',
   ],
+  [
+    'LiteLLMClaudeCodeMarketplacePlugin',
+    'isLiteLLMClaudeCodeMarketplacePlugin',
+    'LiteLLM.ClaudeCodeMarketplacePlugin',
+    'LiteLLMClaudeCodeMarketplacePluginProvider',
+  ],
   ['LiteLLMToolset', 'isLiteLLMToolset', 'LiteLLM.Toolset', 'LiteLLMToolsetProvider'],
   ['LiteLLMPolicy', 'isLiteLLMPolicy', 'LiteLLM.Policy', 'LiteLLMPolicyProvider'],
   [