@homeflare/alchemy 0.52.0 → 0.53.1

package/src/grafana/team.test.ts

@@ -0,0 +1,108 @@
+/**
+ * `Grafana.Team` against a fake Grafana through the real `@distilled.cloud/grafana` protocol:
+ * exact-name observe (adopt), create body, update only on drift, provisioned refusal, idempotent delete.
+ */
+import { describe, expect, test } from 'bun:test';
+import type { GrafanaOpContext } from '@distilled.cloud/grafana/Protocol';
+import * as Effect from 'effect/Effect';
+import { fakeFailure, fakeGrafana, fakeGrafanaLayer } from './fake-grafana.ts';
+import { grafanaOperations } from './resource.ts';
+import { spec } from './team.ts';
+
+const team = (over: Record<string, unknown> = {}) => ({
+  id: 7,
+  uid: 'aex7',
+  name: 'village-grafana',
+  email: '',
+  isProvisioned: false,
+  memberCount: 0,
+  orgId: 1,
+  ...over,
+});
+const search = (teams: unknown[]) =>
+  Response.json({ teams, totalCount: teams.length, page: 1, perPage: 100 });
+const run = <A, E>(
+  fake: ReturnType<typeof fakeGrafana>,
+  effect: Effect.Effect<A, E, GrafanaOpContext>,
+): Promise<A> => Effect.runPromise(effect.pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))));
+const props = { name: 'village-grafana' };
+
+describe('Grafana.Team', () => {
+  test('fetchLive keeps only an exact name match, GET without a body', async () => {
+    const fake = fakeGrafana((m, url) =>
+      m === 'GET' && url.pathname === '/api/teams/search'
+        ? search([team({ name: 'village-grafana-old', id: 9 }), team()])
+        : fakeFailure(404, 'x'),
+    );
+    const live = await run(fake, spec.fetchLive(props));
+    expect(live?.id).toBe(7);
+    expect(fake.bodies[0]).toBeUndefined();
+  });
+
+  test('absent team folds to undefined; 403 propagates', async () => {
+    expect(
+      await run(
+        fakeGrafana(() => search([])),
+        spec.fetchLive(props),
+      ),
+    ).toBeUndefined();
+    const failure = await run(
+      fakeGrafana(() => fakeFailure(403, 'forbidden')),
+      Effect.flip(spec.fetchLive(props)),
+    );
+    expect((failure as { _tag: string })._tag).toBe('Forbidden');
+  });
+
+  test('reconcile adopts a matching live team with no write', async () => {
+    const fake = fakeGrafana((m) =>
+      m === 'GET' ? search([team()]) : fakeFailure(500, 'no write expected'),
+    );
+    const out = await run(fake, grafanaOperations(spec).reconcile(props));
+    expect(out).toMatchObject({ id: 7, name: 'village-grafana' });
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('reconcile creates when absent, sending only declared fields', async () => {
+    let created = false;
+    const fake = fakeGrafana((m) => {
+      if (m === 'POST') {
+        created = true;
+        return Response.json({ teamId: 7, uid: 'aex7', message: 'Team created' });
+      }
+      return search(created ? [team()] : []);
+    });
+    await run(fake, grafanaOperations(spec).reconcile(props));
+    expect(fake.bodies.filter((b) => b !== undefined)).toEqual([{ name: 'village-grafana' }]);
+  });
+
+  test('email drift updates by team id', async () => {
+    let updated = false;
+    const fake = fakeGrafana((m) => {
+      if (m === 'PUT') {
+        updated = true;
+        return Response.json({ message: 'Team updated' });
+      }
+      return search([team({ email: updated ? 'ops@example.com' : '' })]);
+    });
+    await run(fake, grafanaOperations(spec).reconcile({ ...props, email: 'ops@example.com' }));
+    expect(fake.seen.some((s) => s.method === 'PUT' && s.path === '/api/teams/7')).toBe(true);
+  });
+
+  test('a provisioned team refuses update and delete without writing', async () => {
+    const fake = fakeGrafana(() => search([team({ isProvisioned: true, email: 'a@b' })]));
+    const failure = await run(
+      fake,
+      Effect.flip(grafanaOperations(spec).reconcile({ ...props, email: 'ops@example.com' })),
+    );
+    expect((failure as { _tag: string })._tag).toBe('GrafanaProvisionedObjectError');
+    const del = await run(fake, Effect.flip(grafanaOperations(spec).destroy(props)));
+    expect((del as { _tag: string })._tag).toBe('GrafanaProvisionedObjectError');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('delete is idempotent when the team is already gone', async () => {
+    const fake = fakeGrafana(() => search([]));
+    await run(fake, grafanaOperations(spec).destroy(props));
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+});

package/src/grafana/team.ts

@@ -0,0 +1,105 @@
+/**
+ * `Grafana.Team` — a Grafana team, keyed by NAME.
+ *
+ * Walked against `@distilled.cloud/grafana` 0.2.1 (`@homeflare/distilled-grafana`): `searchTeams`,
+ * `createTeam`, `updateTeam`, `deleteTeam`. Upstream Alchemy ships no Grafana family (S1); distilled
+ * ships the SDK, so every call goes through it (S23).
+ *
+ * ★ NAME IS THE KEY, NOT `uid`. `CreateTeamRequest` takes only `name`/`email` — there is no way to
+ *   choose a team uid, and Grafana enforces unique team names per org. `fetchLive` therefore runs
+ *   `GET /teams/search?name=<name>` (an exact-name filter) and keeps only an exact match; adoption of a
+ *   team created by hand or by a script is a plain observe (S9/S10).
+ * ★ `email` is optional and compared only when declared ("undeclared means don't care", the kit's
+ *   convention for optional props).
+ * ⛔ A provisioned team (`isProvisioned`, e.g. synced from SCIM/LDAP) is refused for update and delete.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as grafana from '@distilled.cloud/grafana';
+import * as Effect from 'effect/Effect';
+import { type GrafanaProvisionedObjectError, refuseIfProvisioned } from './provisioned.ts';
+import { type GrafanaSpec, grafanaHandlers } from './resource.ts';
+
+export interface TeamProps {
+  /** Team name — unique per org, and this resource's identity. */
+  name: string;
+  /** Optional team email; compared only when declared. */
+  email?: string;
+}
+
+export interface TeamAttributes {
+  id: number;
+  uid: string;
+  name: string;
+  email: string;
+  isProvisioned: boolean;
+}
+
+export interface GrafanaTeam extends Resource<'Grafana.Team', TeamProps, TeamAttributes, never> {}
+
+export const GrafanaTeam = Resource<GrafanaTeam>('Grafana.Team');
+
+/** Exact-name lookup. `/teams/search?name=` is already exact in Grafana; the filter keeps that true. */
+export const findTeamByName = (name: string) =>
+  grafana
+    .searchTeams({ name, perpage: 100 })
+    .pipe(Effect.map((result) => (result.teams ?? []).find((team) => team.name === name)));
+
+export const spec: GrafanaSpec<
+  TeamProps,
+  grafana.TeamDTO,
+  TeamAttributes,
+  | grafana.SearchTeamsError
+  | grafana.CreateTeamError
+  | grafana.UpdateTeamError
+  | grafana.DeleteTeamError
+  | GrafanaProvisionedObjectError
+> = {
+  attributes: (live) => ({
+    email: live.email ?? '',
+    id: live.id,
+    isProvisioned: live.isProvisioned,
+    name: live.name,
+    uid: live.uid,
+  }),
+  create: (props) =>
+    grafana.createTeam({
+      name: props.name,
+      ...(props.email === undefined ? {} : { email: props.email }),
+    }),
+  destroy: (props, live) =>
+    Effect.gen(function* () {
+      if (live.isProvisioned) {
+        return yield* refuseIfProvisioned(
+          'Grafana.Team',
+          props.name,
+          'an external team sync (isProvisioned)',
+        );
+      }
+      yield* grafana.deleteTeam({ team_id: String(live.id) });
+    }),
+  fetchLive: (props) => findTeamByName(props.name),
+  matches: (attributes, props) =>
+    attributes.name === props.name &&
+    (props.email === undefined || attributes.email === props.email),
+  update: (props, live) =>
+    Effect.gen(function* () {
+      if (live.isProvisioned) {
+        return yield* refuseIfProvisioned(
+          'Grafana.Team',
+          props.name,
+          'an external team sync (isProvisioned)',
+        );
+      }
+      return yield* grafana.updateTeam({
+        team_id: String(live.id),
+        name: props.name,
+        ...(props.email === undefined ? {} : { email: props.email }),
+      });
+    }),
+};
+
+export const handlers = grafanaHandlers(spec);
+
+export const GrafanaTeamProvider = () =>
+  Provider.effect(GrafanaTeam, Effect.succeed(GrafanaTeam.Provider.of(handlers)));

package/src/linux/container-env-quote.test.ts

@@ -15,6 +15,7 @@ import {
   QuadletEnvironmentValueError,
   environmentLines,
   environmentValueProblems,
+  needsQuoting,
   quoteEnvironmentValue,
 } from './container-env-quote.ts';
 import { containerProblems, renderContainerFile } from './container-form.ts';
@@ -62,13 +63,64 @@ describe('the rendered text', () => {
 
   test('keys are sorted, so the render is stable for an unordered plain object', () => {
     expect(environmentLines({ B: '2', A: '1' })).toEqual([
-      ['Environment', '"A=1"'],
-      ['Environment', '"B=2"'],
+      ['Environment', 'A=1'],
+      ['Environment', 'B=2'],
     ]);
     expect(environmentLines({})).toEqual([]);
   });
 });
 
+describe('quoted only when needed (0.53.1)', () => {
+  test('plain values render bare, byte-identical to the 0.51/0.52 renderer', () => {
+    expect(
+      environmentLines({
+        CADDY_CONFIG: '/etc/caddy/Caddyfile',
+        EMPTY: '',
+        URL: 'https://grafana.example/login?a=1&b=2#frag',
+        MIXED: 'a-b_c.d:e/f,g;h@i+j=k(l)[m]{n}*~!|<>?`',
+      }).map(([key, value]) => `${key}=${value}`),
+    ).toEqual([
+      'Environment=CADDY_CONFIG=/etc/caddy/Caddyfile',
+      'Environment=EMPTY=',
+      'Environment=MIXED=a-b_c.d:e/f,g;h@i+j=k(l)[m]{n}*~!|<>?`',
+      'Environment=URL=https://grafana.example/login?a=1&b=2#frag',
+    ]);
+  });
+
+  test.each([
+    ['space', 'a b'],
+    ['tab', 'a\tb'],
+    ['double quote', 'say "hi"'],
+    ['single quote', "it's"],
+    ['percent', '50%off'],
+    ['dollar', 'pa$word'],
+    ['backslash', 'C:\\path'],
+  ])('a value with a %s is quoted', (_name, value) => {
+    expect(needsQuoting(`K=${value}`)).toBe(true);
+    const rendered = quoteEnvironmentValue('K', value);
+    expect(rendered.startsWith('"K=')).toBe(true);
+    expect(rendered.endsWith('"')).toBe(true);
+  });
+
+  test('a single quote alone triggers the full quoted form', () => {
+    expect(quoteEnvironmentValue('K', "it's")).toBe(`"K=it's"`);
+  });
+
+  test('a special character in the KEY also triggers quoting', () => {
+    expect(quoteEnvironmentValue('A%B', '1')).toBe('"A%%B=1"');
+  });
+
+  test('plain values never need quoting', () => {
+    expect(needsQuoting('A=1')).toBe(false);
+    expect(needsQuoting('K=')).toBe(false);
+    expect(quoteEnvironmentValue('A', '1')).toBe('A=1');
+  });
+
+  test('newlines are still refused before the bare/quoted decision', () => {
+    expect(() => quoteEnvironmentValue('K', 'plain\nplain')).toThrow(QuadletEnvironmentValueError);
+  });
+});
+
 describe('newlines are refused, not encoded', () => {
   test('a newline in a value is a typed error naming the key, never the value', () => {
     expect(() => quoteEnvironmentValue('WEBHOOK_URL', 'https://x\nSECRET-TAIL')).toThrow(

package/src/linux/container-env-quote.ts

@@ -65,6 +65,17 @@ export class QuadletEnvironmentValueError extends Data.TaggedError('QuadletEnvir
   }
 }
 
+/**
+ * The characters that make a bare `KEY=value` unsafe: whitespace (quadlet's splitter ends the
+ * assignment there), `"` and `'` (start/end a quoted region), `\\` (C-escape, which can fail the
+ * whole line), `%` (systemd specifier) and `$` (systemd variable expansion). Anything else passes
+ * quadlet, podman's re-emission and systemd's ExecStart parsing unchanged.
+ */
+const SPECIAL = /[\s"'\\%$]/u;
+
+/** True when `assignment` must be wrapped and escaped to survive the three parsers. */
+export const needsQuoting = (assignment: string): boolean => SPECIAL.test(assignment);
+
 /**
  * `Environment="KEY=value"` — the whole assignment double-quoted, with `\`, `"`, `%` and `$`
  * escaped (in that order, over the joined `KEY=value`), so the wrapping quotes this function adds
@@ -76,6 +87,10 @@ export class QuadletEnvironmentValueError extends Data.TaggedError('QuadletEnvir
  */
 export const quoteEnvironmentValue = (key: string, value: string): string => {
   if (key.includes('\n') || value.includes('\n')) throw new QuadletEnvironmentValueError({ key });
+  // ★ QUOTE ONLY WHEN NEEDED (0.53.1): a `KEY=value` with none of the characters any of the three
+  //   parsers treats specially passes all of them verbatim, so it renders bare — byte-identical to
+  //   the 0.51/0.52 renderer, so units holding only plain values do not change (and do not restart).
+  if (!needsQuoting(`${key}=${value}`)) return `${key}=${value}`;
   // ⛔ THE `$` REPLACEMENT MUST BE A FUNCTION — measured 2026-10-12: `replaceAll`'s replacement
   //   STRING runs its own `$`-pattern mini-language (same fold as systemd: `$$` in it IS one
   //   literal `$`, and `$&` is the match), so a plain `'$$'` replacement silently no-ops and the

package/src/linux/container-fixture.test.ts

@@ -66,9 +66,9 @@ test('renders every directive CT100’s live caddy.container carries', () => {
     'ContainerName=caddy',
     'Network=host',
     'EnvironmentFile=/etc/caddy/cf-token.env',
-    // ⛔ Quoted, like every Environment= value now (container-env-quote.ts) — the caddy value has
-    //   no spaces, but uniform quoting is the rule; container-env-quote.test.ts has the story.
-    'Environment="CADDY_CONFIG=/etc/caddy/Caddyfile"',
+    // ★ Bare again since 0.53.1: the value holds nothing any parser treats specially, so it renders
+    //   exactly as the live file (and 0.51/0.52) has it — container-env-quote.ts quotes only when needed.
+    'Environment=CADDY_CONFIG=/etc/caddy/Caddyfile',
     'Volume=/etc/caddy/Caddyfile:/etc/caddy/Caddyfile:ro,Z',
     'Volume=/etc/caddy/rendered:/etc/caddy/rendered:ro,Z',
     'Volume=/etc/caddy/cf-token.env:/run/cf/token.env:ro',

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,