@homeflare/alchemy 0.30.0 → 0.31.1

package/src/discord/command-form.ts

@@ -0,0 +1,133 @@
+/**
+ * The wire body for a Discord command (global or guild), and the comparison that decides whether
+ * it needs writing — shared by `application-command.ts` and `guild-application-command.ts` so the
+ * two specs cannot drift on what "matches" means. Mirrors `../netbox/prefix-form.ts`: pure
+ * functions of the props, extracted so a test can call them with a literal, no server involved.
+ */
+import { deepEqual } from 'alchemy/Diff';
+
+/** Fields every Discord command shares, independent of global vs. guild scope. */
+export interface CommandFields {
+  readonly name: string;
+  readonly description?: string;
+  /**
+   * ⚠️ GAP: passed through opaquely, not re-modeled. The SDK's generated option union is ~40
+   *   nested schema types (subcommand, subcommand group, string/int/number/channel/role/user/
+   *   mentionable/attachment, each with its own choices and localizations) — see
+   *   `docs/upstream-conformance.md#discord`. A caller supplies the exact wire shape from
+   *   Discord's own docs; this resource neither validates nor transforms it.
+   */
+  readonly options?: readonly Record<string, unknown>[];
+  /** Bitfield, stringified, per Discord's real wire contract (the SDK types write as `number`). */
+  readonly defaultMemberPermissions?: string;
+  readonly dmPermission?: boolean;
+  readonly contexts?: readonly number[];
+  readonly integrationTypes?: readonly number[];
+  readonly nsfw?: boolean;
+  /** `ApplicationCommandType`; omitted means `1` (`CHAT_INPUT`), Discord's own default. */
+  readonly type?: number;
+}
+
+export interface CommandFieldsAttributes {
+  readonly name: string;
+  readonly description: string;
+  readonly options: readonly Record<string, unknown>[];
+  readonly defaultMemberPermissions: string | undefined;
+  readonly dmPermission: boolean | undefined;
+  readonly contexts: readonly number[] | undefined;
+  readonly integrationTypes: readonly number[] | undefined;
+  readonly nsfw: boolean;
+  readonly type: number;
+}
+
+const DEFAULT_TYPE = 1;
+
+/** The fields an undeclared prop still settles to, because Discord itself would. */
+const settled = (props: CommandFields) => ({
+  description: props.description ?? '',
+  nsfw: props.nsfw ?? false,
+  type: props.type ?? DEFAULT_TYPE,
+});
+
+/**
+ * ⛔ SENT IN FULL ON EVERY UPSERT, NEVER PARTIAL. Discord's create-as-upsert (resource.ts's own
+ *   note) replaces the whole command, so a body that omitted a field the caller stopped declaring
+ *   would never actually clear it — the same "declared, then forgotten" bug `prefix-form.ts`
+ *   documents for NetBox's PATCH. Sending the full settled shape every time is what keeps a
+ *   removed prop actually removed live, not just removed from the declaration.
+ */
+export const commandBody = (props: CommandFields): Record<string, unknown> => {
+  const fixed = settled(props);
+  const out: Record<string, unknown> = {
+    description: fixed.description,
+    name: props.name,
+    nsfw: fixed.nsfw,
+    type: fixed.type,
+  };
+  if (props.options !== undefined) out['options'] = props.options;
+  if (props.defaultMemberPermissions !== undefined) {
+    out['default_member_permissions'] = props.defaultMemberPermissions;
+  }
+  if (props.dmPermission !== undefined) out['dm_permission'] = props.dmPermission;
+  if (props.contexts !== undefined) out['contexts'] = props.contexts;
+  if (props.integrationTypes !== undefined) out['integration_types'] = props.integrationTypes;
+  return out;
+};
+
+/** Whether the live command already says what the declaration says. */
+export const commandMatches = (
+  attributes: CommandFieldsAttributes,
+  props: CommandFields,
+): boolean => {
+  const fixed = settled(props);
+  return (
+    attributes.name === props.name &&
+    attributes.description === fixed.description &&
+    attributes.nsfw === fixed.nsfw &&
+    attributes.type === fixed.type &&
+    // ⛔ GATED LIKE EVERY OTHER OPTIONAL FIELD BELOW — an undeclared `options` means "not mine",
+    //   in both directions (this file's own header rule). An earlier version of this line
+    //   compared unconditionally against `props.options ?? []`: a declaration with no `options`
+    //   at all would then see live options as drift, `commandBody` (which already omits
+    //   `options` when undeclared) would upsert without it, and Discord's real full-replace
+    //   create would silently wipe a live command's arguments on the first non-dry-run deploy.
+    //   Caught in review before merge, not measured live.
+    (props.options === undefined || deepEqual(attributes.options, props.options)) &&
+    (props.defaultMemberPermissions === undefined ||
+      attributes.defaultMemberPermissions === props.defaultMemberPermissions) &&
+    (props.dmPermission === undefined || attributes.dmPermission === props.dmPermission) &&
+    (props.contexts === undefined || deepEqual(attributes.contexts, props.contexts)) &&
+    (props.integrationTypes === undefined ||
+      deepEqual(attributes.integrationTypes, props.integrationTypes))
+  );
+};
+
+/**
+ * Reads the shared fields off any `ApplicationCommandResponse`-shaped object.
+ *
+ * ⚠️ `options` IS READ AS `readonly unknown[]`, NOT RE-TYPED. The SDK's real
+ *   `ApplicationCommandResponseOptionsItem` union has no index signature (each option kind is a
+ *   distinct generated interface), so it cannot structurally satisfy `Record<string, unknown>`
+ *   without a cast — the same "opaque passthrough" gap `CommandFields.options` documents above.
+ */
+export const commandFieldsOf = (live: {
+  readonly name: string;
+  readonly description: string;
+  readonly options?: readonly unknown[] | null | undefined;
+  readonly default_member_permissions?: string | null | undefined;
+  readonly dm_permission?: boolean | undefined;
+  readonly contexts?: readonly number[] | null | undefined;
+  readonly integration_types?: readonly number[] | null | undefined;
+  readonly nsfw?: boolean | undefined;
+  readonly type: number;
+}): CommandFieldsAttributes => ({
+  contexts: live.contexts ?? undefined,
+  defaultMemberPermissions: live.default_member_permissions ?? undefined,
+  description: live.description,
+  dmPermission: live.dm_permission,
+  integrationTypes: live.integration_types ?? undefined,
+  name: live.name,
+  nsfw: live.nsfw === true,
+  options: (live.options as readonly Record<string, unknown>[] | null | undefined) ?? [],
+  type: live.type,
+});

package/src/discord/credentials.ts

@@ -0,0 +1,36 @@
+/**
+ * Discord credentials — a bot token REFERENCE, resolved lazily (S24), never a prop.
+ *
+ * ⛔ NO TOKEN IS EVER A PROP OR AN ATTRIBUTE. Alchemy persists Attributes unencrypted
+ *   (State/StateEncoding.ts@v2.0.0-beta.79#encodeState), so nothing a stack file holds may be a
+ *   credential. `@distilled.cloud/discord/Credentials` already ships exactly the shape S24 asks
+ *   for: `Credentials` is a lazy `Context.Service<Credentials, Effect.Effect<Config>>`, resolved
+ *   on the calling fiber inside each operation (`DiscordProtocol`'s `credentials:` field), never
+ *   at layer build. This file re-exports it rather than re-implementing it — the same choice
+ *   `../netbox/resource.ts` made for `CredentialsFromEnv` — and adds only the house-specific
+ *   naming and doc trail.
+ *
+ * ★ `CredentialsFromEnv` reads `DISCORD_BOT_TOKEN` (falling back to `DISCORD_TOKEN`) via Effect's
+ *   `Config`, which is exactly the "reference" shape S25 asks for: the resource never sees the
+ *   value, only the environment variable NAME is anywhere near a stack file, and the value itself
+ *   is wrapped in `Redacted` the moment it is read.
+ *
+ * ⚠️ NO OpenBao MINT YET. H8's target (`Alchemy.Stack({ secrets })`) is unreleased (PR 1728, still
+ *   on `main` only). Until the estate is on a release that carries it, the deploy process's own
+ *   environment is the credential seam — a human or CI job exports `DISCORD_BOT_TOKEN` from
+ *   wherever it mints it (on CT100 today: `/opt/homeflare/env/discord-halibut.env`, read by
+ *   systemd's `EnvironmentFile=`, never by this package). This package never reads that file.
+ */
+import type { Config } from '@distilled.cloud/discord/Credentials';
+import { Credentials, CredentialsFromEnv, credentials } from '@distilled.cloud/discord/Credentials';
+
+/** Re-exported so a consumer never has to reach into `@distilled.cloud/discord` by hand. */
+export { Credentials, CredentialsFromEnv, credentials };
+export type { Config as DiscordCredentialsConfig };
+
+/**
+ * `DiscordCredentials.fromEnv()` — the layer every `discordProviders()` stack uses by default.
+ * A thin, named alias over `CredentialsFromEnv` so a stack's import reads `Discord.*`
+ * throughout, the way `../netbox/index.ts`'s barrel keeps `Netbox*` names at the front door.
+ */
+export const fromEnv = () => CredentialsFromEnv;

package/src/discord/fake-discord.ts

@@ -0,0 +1,70 @@
+/**
+ * A minimal in-memory Discord REST API for this family's tests — an in-memory `fetch` handed to
+ * Effect's real `FetchHttpClient` through its `Fetch` reference, mirroring `../netbox/fake-netbox.ts`
+ * (itself mirroring `../forgejo/fake-forgejo.ts` and `cloudflare/fake-mesh.ts`). Tests exercise
+ * distilled's REAL path assembly, JSON encode/decode, status→typed-error matching AND its retry
+ * policy — nothing about any of that is re-implemented here, only the wire responses a scenario
+ * needs, including a `429` with a `Retry-After` header for the bounded-retry test.
+ *
+ * ⛔ TEST-ONLY, AND NO NETWORK. No provider imports this file. The base URL is RFC 2606
+ *   `discord.example.com`, and the token is a placeholder.
+ */
+import { type Credentials, credentials } from '@distilled.cloud/discord/Credentials';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+
+export const FAKE_BASE = 'https://discord.example.com';
+export const FAKE_TOKEN = 'placeholder-discord-token';
+
+export type Seen = { readonly method: string; readonly path: string; readonly body: unknown };
+
+/** Discord's `{ code, message }` failure envelope — matching `protocol.ts`'s `errorEnvelope`. */
+export const fakeFailure = (
+  status: number,
+  code: number,
+  message: string,
+  headers?: Record<string, string>,
+) => Response.json({ code, message }, headers === undefined ? { status } : { headers, status });
+
+/** A `429` with `Retry-After` in seconds, Discord's real shape for a rate-limited response. */
+export const fakeRateLimited = (retryAfterSeconds: number) =>
+  fakeFailure(429, 20028, 'You are being rate limited.', {
+    'Retry-After': String(retryAfterSeconds),
+  });
+
+/**
+ * `route` decides every response; this wrapper only records what was sent and adapts to
+ * `globalThis.fetch`'s signature. A test that expects no request at all asserts `seen` is empty.
+ */
+export const fakeDiscord = (
+  route: (method: string, url: URL, body: unknown, callNumber: number) => Response,
+) => {
+  const seen: Seen[] = [];
+  let callNumber = 0;
+  const fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const url = new URL(request.url);
+    const bodyText = await request.clone().text();
+    const body: unknown = bodyText === '' ? undefined : JSON.parse(bodyText);
+    seen.push({ body, method: request.method, path: `${url.pathname}${url.search}` });
+    callNumber += 1;
+    return route(request.method, url, body, callNumber);
+  }) as typeof globalThis.fetch;
+  return { fetch, seen };
+};
+
+/**
+ * distilled Credentials + the real FetchHttpClient over the fake — `DiscordOpContext`, what every
+ * resource file's exported `spec.fetchByName`/`spec.upsert`/`spec.destroy` needs.
+ *
+ * ⚠️ NOT PAIRED WITH `handlers` (each resource file's `discordHandlers(spec)` export). `handlers`
+ *   bakes in `CredentialsFromEnv`, which resolves through Effect's `Config` snapshot of
+ *   `process.env` — the same seam `../netbox/fake-netbox.ts` documents as untestable against a
+ *   fake server. So a test calls `spec.fetchByName`/`spec.upsert`/`spec.destroy` directly, with
+ *   this explicit layer, exercising exactly the same production code without that env seam.
+ */
+export const fakeDiscordLayer = (
+  fetchFn: typeof globalThis.fetch,
+  creds: Layer.Layer<Credentials> = credentials({ apiBaseUrl: FAKE_BASE, token: FAKE_TOKEN }),
+) => Layer.mergeAll(creds, FetchHttpClient.layer, Layer.succeed(FetchHttpClient.Fetch, fetchFn));

package/src/discord/guild-application-command.test.ts

@@ -0,0 +1,215 @@
+/**
+ * `Discord.GuildApplicationCommand`'s `spec` against a fake Discord, proving the real distilled
+ * wire path — path assembly, JSON encode/decode and typed-error matching — exercised through
+ * `@distilled.cloud/discord/discord`'s real operations, never re-implemented here. Also proves
+ * `discordOperations(spec)`'s read/reconcile flow (resource.ts), the exact object `discordHandlers`
+ * wraps into `DiscordGuildApplicationCommandProvider`. Mirrors `../netbox/prefix.test.ts`.
+ */
+import { describe, expect, test } from 'bun:test';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import type * as command from '@distilled.cloud/discord/discord';
+import * as Effect from 'effect/Effect';
+import { FAKE_BASE, fakeDiscord, fakeDiscordLayer, fakeFailure } from './fake-discord.ts';
+import type { GuildApplicationCommandProps } from './guild-application-command.ts';
+import { spec } from './guild-application-command.ts';
+import { discordOperations } from './resource.ts';
+
+const APP = '111111111111111111';
+const GUILD = '222222222222222222';
+const CMD_PATH = `/applications/${APP}/guilds/${GUILD}/commands`;
+const PROPS: GuildApplicationCommandProps = {
+  applicationId: APP,
+  description: 'ping the bot',
+  guildId: GUILD,
+  name: 'ping',
+};
+
+/** Loosely typed on purpose — a fixture, cast to the real response shape at the boundary. */
+const liveCommand = (overrides: Record<string, unknown> = {}) =>
+  ({
+    application_id: APP,
+    default_member_permissions: null,
+    description: 'ping the bot',
+    guild_id: GUILD,
+    id: '999',
+    name: 'ping',
+    nsfw: false,
+    type: 1,
+    version: '1',
+    ...overrides,
+  }) as unknown as command.ApplicationCommandResponse;
+
+describe('Discord.GuildApplicationCommand spec.fetchByName', () => {
+  test('finds the row whose name matches, among others', async () => {
+    const fake = fakeDiscord((method, url) =>
+      method === 'GET' && url.pathname === CMD_PATH
+        ? Response.json([
+            liveCommand({ id: '1', name: 'other' }),
+            liveCommand({ id: '999', name: 'ping' }),
+          ])
+        : fakeFailure(400, 0, 'unexpected request'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchByName(PROPS).pipe(Effect.provide(fakeDiscordLayer(fake.fetch))),
+    );
+    expect(live?.id).toBe('999');
+    expect(fake.seen[0]?.method).toBe('GET');
+  });
+
+  test('no matching name is absent, not an error', async () => {
+    const fake = fakeDiscord(() => Response.json([liveCommand({ name: 'other' })]));
+    const live = await Effect.runPromise(
+      spec.fetchByName(PROPS).pipe(Effect.provide(fakeDiscordLayer(fake.fetch))),
+    );
+    expect(live).toBeUndefined();
+  });
+
+  /**
+   * ⚠️ 401, NOT 403. MEASURED: the SDK types every generated Discord operation's error channel
+   *   as exactly `DiscordOpError` — `DefaultErrors | ConfigError | HttpClientError`, which core's
+   *   `errors.ts` builds only from `DEFAULT_ERROR_STATUSES` (401/429/500/502/503/504). 403
+   *   (`Forbidden`), 404 (`NotFound`), 400 (`BadRequest`) and 409 (`Conflict`) are NOT in that
+   *   type, even though `HTTP_STATUS_MAP` maps them at runtime — see `docs/discord.md#sdk-gaps`.
+   *   401 is the smallest real status this SDK's own type actually declares for a propagating
+   *   failure, so it is what this test can assert without an unsafe cast past the type checker.
+   */
+  test('a 401 propagates — never folded to absent', async () => {
+    const fake = fakeDiscord(() => fakeFailure(401, 0, 'Unauthorized'));
+    const failure = await Effect.runPromise(
+      Effect.flip(spec.fetchByName(PROPS).pipe(Effect.provide(fakeDiscordLayer(fake.fetch)))),
+    );
+    expect(failure._tag).toBe('Unauthorized');
+  });
+});
+
+describe('Discord.GuildApplicationCommand spec.attributes', () => {
+  test('decodes the shared fields plus the guild-specific ones', () => {
+    expect(spec.attributes(liveCommand({ default_member_permissions: '8' }))).toEqual({
+      applicationId: APP,
+      commandId: '999',
+      contexts: undefined,
+      defaultMemberPermissions: '8',
+      description: 'ping the bot',
+      dmPermission: undefined,
+      guildId: GUILD,
+      integrationTypes: undefined,
+      name: 'ping',
+      nsfw: false,
+      options: [],
+      type: 1,
+      version: '1',
+    });
+  });
+});
+
+describe('discordOperations(spec).reconcile — S10, zero write calls when there is no drift', () => {
+  test('a live command that already matches is left alone', async () => {
+    const fake = fakeDiscord((method, url) =>
+      method === 'GET' && url.pathname === CMD_PATH
+        ? Response.json([liveCommand()])
+        : fakeFailure(500, 0, 'unexpected POST'),
+    );
+    const ops = discordOperations(spec);
+    const attrs = await Effect.runPromise(
+      ops.reconcile(PROPS).pipe(Effect.provide(fakeDiscordLayer(fake.fetch))),
+    );
+    expect(attrs.commandId).toBe('999');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('a description that drifted is converged with one upsert call, full body', async () => {
+    const fake = fakeDiscord((method, url) => {
+      if (method === 'GET' && url.pathname === CMD_PATH) {
+        return Response.json([liveCommand({ description: 'stale' })]);
+      }
+      if (method === 'POST' && url.pathname === CMD_PATH) {
+        return Response.json(liveCommand({ description: 'ping the bot' }));
+      }
+      return fakeFailure(400, 0, 'unexpected request');
+    });
+    const ops = discordOperations(spec);
+    const attrs = await Effect.runPromise(
+      ops.reconcile(PROPS).pipe(Effect.provide(fakeDiscordLayer(fake.fetch))),
+    );
+    expect(attrs.description).toBe('ping the bot');
+    const post = fake.seen.find((s) => s.method === 'POST');
+    expect(post?.body).toMatchObject({ description: 'ping the bot', name: 'ping' });
+  });
+
+  test('absent live command is created with the full declared body', async () => {
+    const fake = fakeDiscord((method, url) => {
+      if (method === 'GET' && url.pathname === CMD_PATH) return Response.json([]);
+      if (method === 'POST' && url.pathname === CMD_PATH) return Response.json(liveCommand());
+      return fakeFailure(400, 0, 'unexpected request');
+    });
+    const ops = discordOperations(spec);
+    await Effect.runPromise(
+      ops.reconcile(PROPS).pipe(Effect.provide(fakeDiscordLayer(fake.fetch))),
+    );
+    expect(fake.seen.filter((s) => s.method === 'POST')).toHaveLength(1);
+  });
+});
+
+describe('discordOperations(spec).read — S7/S8, Unowned on a cold match, plain on a warm one', () => {
+  test('cold (no persisted output) + a live match: Unowned, so adopt is gated', async () => {
+    const fake = fakeDiscord(() => Response.json([liveCommand()]));
+    const ops = discordOperations(spec);
+    const result = await Effect.runPromise(
+      ops
+        .read({ olds: PROPS, output: undefined })
+        .pipe(Effect.provide(fakeDiscordLayer(fake.fetch))),
+    );
+    expect(result).toBeDefined();
+    expect(Unowned.is(result)).toBe(true);
+  });
+
+  test('warm (persisted output from a prior apply) + a live match: plain attributes, ours already', async () => {
+    const fake = fakeDiscord(() => Response.json([liveCommand()]));
+    const ops = discordOperations(spec);
+    const priorAttrs = spec.attributes(liveCommand());
+    const result = await Effect.runPromise(
+      ops
+        .read({ olds: PROPS, output: priorAttrs })
+        .pipe(Effect.provide(fakeDiscordLayer(fake.fetch))),
+    );
+    expect(Unowned.is(result)).toBe(false);
+    expect(result).toEqual(priorAttrs);
+  });
+
+  test('no live match at all: undefined, regardless of warm/cold', async () => {
+    const fake = fakeDiscord(() => Response.json([]));
+    const ops = discordOperations(spec);
+    const result = await Effect.runPromise(
+      ops
+        .read({ olds: PROPS, output: undefined })
+        .pipe(Effect.provide(fakeDiscordLayer(fake.fetch))),
+    );
+    expect(result).toBeUndefined();
+  });
+});
+
+describe('discordOperations(spec).destroy', () => {
+  test('deletes the live command by id', async () => {
+    const fake = fakeDiscord((method, url) => {
+      if (method === 'GET' && url.pathname === CMD_PATH) return Response.json([liveCommand()]);
+      if (method === 'DELETE' && url.pathname === `${CMD_PATH}/999`)
+        return new Response(null, { status: 204 });
+      return fakeFailure(400, 0, 'unexpected request');
+    });
+    const ops = discordOperations(spec);
+    await Effect.runPromise(ops.destroy(PROPS).pipe(Effect.provide(fakeDiscordLayer(fake.fetch))));
+    expect(fake.seen.some((s) => s.method === 'DELETE')).toBe(true);
+  });
+
+  test('an already-gone command is a no-op delete, not an error', async () => {
+    const fake = fakeDiscord(() => Response.json([]));
+    const ops = discordOperations(spec);
+    await Effect.runPromise(ops.destroy(PROPS).pipe(Effect.provide(fakeDiscordLayer(fake.fetch))));
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+});
+
+// `FAKE_BASE` proves the fake's own origin never leaks past the layer boundary into a real host.
+test('fake-discord never points at a real host', () => {
+  expect(FAKE_BASE).toBe('https://discord.example.com');
+});

package/src/discord/guild-application-command.ts

@@ -0,0 +1,129 @@
+/**
+ * `Discord.GuildApplicationCommand` — one guild-scoped slash/user/message command.
+ *
+ * 🔴 THIS IS WHAT `hf-discord-halibut.service` OWNS TODAY, AND DECLARING IT AGAINST HALIBUT'S OWN
+ *   GUILDS WOULD FIGHT THE BOT, NOT REPLACE IT. Halibut calls `applySapphireGuildRegister()`
+ *   before every login (`src/discord/register.ts` on CT100, `RegisterBehavior.BulkOverwrite`),
+ *   which PUTs its exact `CURRENT_SLASH_NAMES` set on every restart. Deploying this resource
+ *   against the same `(applicationId, guildId)` the bot manages means two owners converging the
+ *   same object on two different schedules — the bot's restart would silently undo whatever this
+ *   resource last wrote, and the next `alchemy plan` would then report drift the bot just caused,
+ *   forever. See `docs/discord.md#halibut` for the measured command list, guild id source, and the
+ *   handover sequence (freeze the list, adopt each command with `adopt(true)` for a verified
+ *   no-op, THEN remove `applySapphireGuildRegister()` from the bot in the same deploy window —
+ *   bot-runtime code, explicitly out of scope for this family).
+ *
+ * ★ Until that handover happens, this resource is for guilds/applications Halibut does not touch.
+ */
+import { adopt } from 'alchemy/AdoptPolicy';
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as command from '@distilled.cloud/discord/discord';
+import type { DiscordOpError } from '@distilled.cloud/discord/Protocol';
+import * as Effect from 'effect/Effect';
+import {
+  type CommandFields,
+  type CommandFieldsAttributes,
+  commandBody,
+  commandFieldsOf,
+  commandMatches,
+} from './command-form.ts';
+import type { DiscordRequirements, DiscordSpec } from './resource.ts';
+import { discordHandlers } from './resource.ts';
+
+export interface GuildApplicationCommandProps extends CommandFields {
+  /** The Discord application (bot) this command belongs to — a public snowflake, not a secret. */
+  applicationId: string;
+  /** The guild (server) this command is scoped to — a public snowflake. */
+  guildId: string;
+}
+
+export interface GuildApplicationCommandAttributes extends CommandFieldsAttributes {
+  commandId: string;
+  applicationId: string;
+  guildId: string;
+  version: string;
+}
+
+export interface DiscordGuildApplicationCommand extends Resource<
+  'Discord.GuildApplicationCommand',
+  GuildApplicationCommandProps,
+  GuildApplicationCommandAttributes,
+  never,
+  DiscordRequirements
+> {}
+
+export const DiscordGuildApplicationCommand = Resource<DiscordGuildApplicationCommand>(
+  'Discord.GuildApplicationCommand',
+  { defaultRemovalPolicy: 'retain' },
+);
+
+export const isDiscordGuildApplicationCommand = (
+  value: unknown,
+): value is DiscordGuildApplicationCommand =>
+  typeof value === 'object' &&
+  value !== null &&
+  (value as { Type?: unknown }).Type === 'Discord.GuildApplicationCommand';
+
+const attributesOf = (
+  live: command.ApplicationCommandResponse,
+): GuildApplicationCommandAttributes => ({
+  applicationId: live.application_id,
+  commandId: live.id,
+  // ⚠️ `guild_id` is present on every row a GUILD list call returns (Discord scopes the list by
+  //   guild), so this cast documents that guarantee rather than re-deriving it from `props`.
+  guildId: live.guild_id as string,
+  version: live.version,
+  ...commandFieldsOf(live),
+});
+
+/** Exported for direct testing against `fake-discord.ts`. */
+export const spec: DiscordSpec<
+  GuildApplicationCommandProps,
+  command.ApplicationCommandResponse,
+  GuildApplicationCommandAttributes,
+  DiscordOpError
+> = {
+  attributes: attributesOf,
+  describe: (props) =>
+    `applications/${props.applicationId}/guilds/${props.guildId}/commands ${props.name}`,
+  destroy: (props, live) =>
+    command.deleteGuildApplicationCommand({
+      application_id: props.applicationId,
+      command_id: live.id,
+      guild_id: props.guildId,
+    }),
+  fetchByName: (props) =>
+    command
+      .listGuildApplicationCommands({
+        application_id: props.applicationId,
+        guild_id: props.guildId,
+      })
+      .pipe(Effect.map((rows) => rows.find((row) => row.name === props.name))),
+  matches: commandMatches,
+  upsert: (props, body) =>
+    command.createGuildApplicationCommand({
+      application_id: props.applicationId,
+      guild_id: props.guildId,
+      ...(body as Omit<
+        command.CreateGuildApplicationCommandRequest,
+        'application_id' | 'guild_id'
+      >),
+    }),
+  upsertBody: commandBody,
+};
+
+export const handlers = discordHandlers(spec);
+
+export const DiscordGuildApplicationCommandProvider = () =>
+  Provider.effect(
+    DiscordGuildApplicationCommand,
+    Effect.succeed(DiscordGuildApplicationCommand.Provider.of(handlers)),
+  );
+
+/**
+ * `guildApplicationCommand('ping', { applicationId, guildId, name: 'ping' })` — `adopt(true)`
+ *   piped on by default (H5). See the file header before pointing this at a guild Halibut manages.
+ */
+export const guildApplicationCommand = (id: string, props: GuildApplicationCommandProps) =>
+  DiscordGuildApplicationCommand(id, props).pipe(adopt(true));

package/src/discord/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Discord providers for Alchemy.
+ *
+ * ⛔ THIS BARREL IS THE PUBLIC API, AND IT IS DELIBERATELY SMALLER THAN THE DIRECTORY. `resource.ts`
+ *   and `command-form.ts` are internals both resource files share — a consumer builds against the
+ *   two commands and `providers()`, not the engine underneath.
+ */
+export {
+  applicationCommand,
+  DiscordApplicationCommand,
+  DiscordApplicationCommandProvider,
+  isDiscordApplicationCommand,
+  type ApplicationCommandAttributes,
+  type ApplicationCommandProps,
+} from './application-command.ts';
+export {
+  Credentials,
+  CredentialsFromEnv,
+  type DiscordCredentialsConfig,
+  credentials,
+  fromEnv,
+} from './credentials.ts';
+export {
+  guildApplicationCommand,
+  DiscordGuildApplicationCommand,
+  DiscordGuildApplicationCommandProvider,
+  isDiscordGuildApplicationCommand,
+  type GuildApplicationCommandAttributes,
+  type GuildApplicationCommandProps,
+} from './guild-application-command.ts';
+export { providers } from './providers.ts';

package/src/discord/providers.ts

@@ -0,0 +1,18 @@
+/**
+ * Both Discord command providers as one layer for a stack.
+ *
+ *     Layer.mergeAll(discordProviders(), …the stack's other providers)
+ *       .pipe(Layer.provide(FetchHttpClient.layer))
+ *
+ * S16: a subpath's `providers()` plays the role upstream's own `Providers.ts` does — one minimal
+ * insertion per family, requirements that never contain `unknown`. `FetchHttpClient.layer` is the
+ * stack's own responsibility to provide (it is the shared transport every family needs, not
+ * something a single vendor's `providers()` should pin), mirroring `../netbox/index.ts`'s barrel,
+ * which exports `netboxHandlers` rather than a bundled transport too.
+ */
+import * as Layer from 'effect/Layer';
+import { DiscordApplicationCommandProvider } from './application-command.ts';
+import { DiscordGuildApplicationCommandProvider } from './guild-application-command.ts';
+
+export const providers = () =>
+  Layer.mergeAll(DiscordApplicationCommandProvider(), DiscordGuildApplicationCommandProvider());