@homeflare/alchemy 0.29.1 → 0.31.0

package/src/caddy/format.test.ts

@@ -0,0 +1,105 @@
+/**
+ * formatCaddyfile()'s Effect wiring, proven against a fake `caddy` — a tiny shell script that
+ * "formats" by stripping trailing whitespace per line — so stdin-in/stdout-out plumbing, the
+ * exit-code check and missing-binary detection are exercised without a real Caddy on the runner.
+ * The last block runs the REAL `caddy fmt` and is skipped, its name saying why, when there is none
+ * on PATH (S42: tests are Bun-native, so `Bun.which` decides, not a hand-rolled PATH search).
+ */
+import { afterAll, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { layer as BunServicesLayer } from '@effect/platform-bun/BunServices';
+import * as Effect from 'effect/Effect';
+import { CaddyFmtFailed, CaddyFmtNotFound, formatCaddyfile } from './format.ts';
+
+/** Only understands `fmt -`: stdin in, "formatted" stdout out — `FAIL_MARKER` fakes a bad parse. */
+const FAKE_SCRIPT = `#!/bin/sh
+if [ "$1" != "fmt" ] || [ "$2" != "-" ]; then
+  echo "fake caddy: unexpected args: $*" >&2
+  exit 2
+fi
+input="$(cat)"
+case "$input" in
+  *FAIL_MARKER*)
+    echo "fake caddy: syntax error" >&2
+    exit 1
+    ;;
+esac
+printf '%s' "$input" | sed -E 's/[[:space:]]+$//'
+`;
+
+const dir = mkdtempSync(join(tmpdir(), 'hf-caddy-fmt-'));
+const fakeBinary = join(dir, 'hf-fake-caddy');
+writeFileSync(fakeBinary, FAKE_SCRIPT, { mode: 0o755 });
+afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+const run = (text: string, options?: Parameters<typeof formatCaddyfile>[1]) =>
+  Effect.runPromise(formatCaddyfile(text, options).pipe(Effect.provide(BunServicesLayer)));
+
+const runFailure = (text: string, options?: Parameters<typeof formatCaddyfile>[1]) =>
+  Effect.runPromise(
+    formatCaddyfile(text, options).pipe(Effect.provide(BunServicesLayer), Effect.flip),
+  );
+
+describe('formatCaddyfile — Effect wiring against a fake binary', () => {
+  test('pipes text to stdin and returns the formatted stdout', async () => {
+    // ⚠️ The fake reads stdin through `$(cat)`, which — like real shell command substitution —
+    //   drops a trailing newline; that is the fake's plumbing, not formatCaddyfile()'s.
+    const out = await run('foo   \nbar\t\n', { binaryPath: fakeBinary });
+    expect(out).toBe('foo\nbar');
+  });
+
+  test('a non-zero exit becomes a typed CaddyFmtFailed, stderr included — never the input back', async () => {
+    const failure = await runFailure('site FAIL_MARKER', { binaryPath: fakeBinary });
+    expect(failure).toBeInstanceOf(CaddyFmtFailed);
+    expect((failure as CaddyFmtFailed).exitCode).toBe(1);
+    expect(failure.message).toContain('syntax error');
+  });
+
+  test('a missing binary fails with the typed CaddyFmtNotFound — never silently skipped', async () => {
+    const missing = join(dir, 'does-not-exist-caddy');
+    const failure = await runFailure('x', { binaryPath: missing });
+    expect(failure).toBeInstanceOf(CaddyFmtNotFound);
+    expect((failure as CaddyFmtNotFound).binaryPath).toBe(missing);
+    expect(failure.message).toContain(missing);
+  });
+
+  test('the default binary name resolves through PATH, not only an absolute path', async () => {
+    const pathDir = mkdtempSync(join(tmpdir(), 'hf-caddy-fmt-path-'));
+    writeFileSync(join(pathDir, 'caddy'), FAKE_SCRIPT, { mode: 0o755 });
+    const original = process.env['PATH'];
+    // ★ Prepended, so this fake wins even when a real `caddy` also sits on PATH.
+    process.env['PATH'] = `${pathDir}:${original ?? ''}`;
+    try {
+      expect(await run('baz  \n')).toBe('baz');
+    } finally {
+      process.env['PATH'] = original;
+      rmSync(pathDir, { recursive: true, force: true });
+    }
+  });
+});
+
+const realCaddy = Bun.which('caddy');
+// ⚠️ DELIBERATELY NOT `caddy fmt`'s own canonical style — no space before `{`, spaces instead of
+//   a tab, and the closing brace indented — every one of which `caddy fmt` actually rewrites, so
+//   `expect(formatted).not.toBe(UNFORMATTED)` below cannot pass by accident on already-formatted
+//   input. (Caught in review: a tab-indented, flush-brace fixture here IS canonical caddy fmt
+//   style, which would make that assertion fail on a correctly working formatCaddyfile().)
+const UNFORMATTED = 'example.com{\n    reverse_proxy 127.0.0.1:8080\n    }\n';
+
+describe('formatCaddyfile — real caddy binary', () => {
+  test.skipIf(realCaddy === null)(
+    realCaddy === null
+      ? 'formats a known-unformatted Caddyfile (skipped: no caddy on PATH)'
+      : 'formats a known-unformatted Caddyfile, and formatting twice is idempotent',
+    async () => {
+      const formatted = await run(UNFORMATTED);
+      expect(formatted).not.toBe(UNFORMATTED);
+      // ★ THE REAL PROOF IT IS FORMATTED: running caddy's own formatter over its own output changes
+      //   nothing. (Never asserted against a fixed expected string — that would pin this test to
+      //   one caddy build's exact formatting choices.)
+      expect(await run(formatted)).toBe(formatted);
+    },
+  );
+});

package/src/caddy/format.ts

@@ -0,0 +1,121 @@
+/**
+ * `formatCaddyfile(text)` — pipes a Caddyfile through the LOCAL `caddy fmt -` binary (stdin in,
+ * formatted text out), the same formatter the `caddy fmt` CLI command runs
+ * (caddyconfig/caddyfile Format in caddyserver/caddy).
+ *
+ * ⛔ THERE IS NO ADMIN API FOR THIS. `caddy fmt` is a CLI-only feature (cmd/commandfuncs.go); no
+ *   `/adapt`, `/load` or other admin endpoint formats a Caddyfile, so this never belongs in
+ *   `@distilled.cloud/caddy` — measured 2026-09-24. It shells out instead, the same pattern
+ *   talos/talosctl.ts uses for a vendor CLI Alchemy does not wrap.
+ * ⛔ NEVER REIMPLEMENTED IN TS. The Caddyfile grammar's formatting rules live in the Go adapter;
+ *   a hand-rolled formatter would drift from it silently. This module only ever runs the real
+ *   binary.
+ * ⛔ A MISSING OR FAILING BINARY FAILS THE EFFECT — IT NEVER RETURNS THE INPUT UNCHANGED.
+ *   `CaddyFmtNotFound` and `CaddyFmtFailed` are typed, catchTag-able failures (S21); there is no
+ *   fallback path that silently skips formatting.
+ * ★ WHY THIS MATTERS: admin-calls.ts's module doc — Caddy's adapter warns "Caddyfile input is not
+ *   formatted" on EVERY unformatted input (adapter.go FormattingDifference), which shares the
+ *   `/load` response body with the refused-but-200 trap. format-warnings.ts surfaces that warning
+ *   distinctly in plan/deploy output; this function is how a caller silences it — by formatting
+ *   the Caddyfile before declaring it, not by ignoring the warning.
+ */
+import * as Effect from 'effect/Effect';
+import * as Stream from 'effect/Stream';
+import * as ChildProcess from 'effect/unstable/process/ChildProcess';
+import * as ChildProcessSpawner from 'effect/unstable/process/ChildProcessSpawner';
+import type * as PlatformError from 'effect/PlatformError';
+
+/** `caddy` resolved on `PATH`, unless the caller points at a specific build. */
+export const DEFAULT_CADDY_BINARY = 'caddy';
+
+/** The configured binary is not on `PATH` (or not executable) — install Caddy, or fix the path. */
+export class CaddyFmtNotFound extends Error {
+  readonly _tag = 'CaddyFmtNotFound';
+  constructor(
+    readonly binaryPath: string,
+    cause: PlatformError.PlatformError,
+  ) {
+    super(
+      `formatCaddyfile: "${binaryPath}" was not found (${cause.message}). Install Caddy so it is ` +
+        'on PATH, or pass { binaryPath } naming the exact build the target Caddy runs.',
+    );
+    this.name = 'CaddyFmtNotFound';
+  }
+}
+
+/** The binary ran but exited non-zero — a syntax error in `text`, most likely. */
+export class CaddyFmtFailed extends Error {
+  readonly _tag = 'CaddyFmtFailed';
+  constructor(
+    readonly binaryPath: string,
+    readonly exitCode: number,
+    stderr: string,
+  ) {
+    super(
+      `formatCaddyfile: "${binaryPath} fmt -" exited ${String(exitCode)}: ${stderr.slice(0, 300)}`,
+    );
+    this.name = 'CaddyFmtFailed';
+  }
+}
+
+export type FormatCaddyfileOptions = {
+  /** The `caddy` binary to run `fmt -` against. @default DEFAULT_CADDY_BINARY, resolved on PATH. */
+  readonly binaryPath?: string;
+};
+
+/**
+ * Format a Caddyfile the way `caddy fmt` would, by actually running it — never a TS
+ * reimplementation. Requires `ChildProcessSpawner` (S19: no `node:child_process`, no
+ * `async`/`await`); provide `@effect/platform-node`'s or `@effect/platform-bun`'s layer.
+ */
+export const formatCaddyfile = (
+  text: string,
+  options: FormatCaddyfileOptions = {},
+): Effect.Effect<
+  string,
+  // ⚠️ A raw PlatformError still escapes for anything that is not "missing binary" (a permission
+  //   problem, a process the OS killed mid-run) — narrower than that would misname what happened.
+  CaddyFmtNotFound | CaddyFmtFailed | PlatformError.PlatformError,
+  ChildProcessSpawner.ChildProcessSpawner
+> =>
+  Effect.gen(function* () {
+    const binaryPath = options.binaryPath ?? DEFAULT_CADDY_BINARY;
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    const input = new TextEncoder().encode(text);
+    const result = yield* ChildProcess.make(binaryPath, ['fmt', '-'], {
+      detached: false,
+      stderr: 'pipe',
+      stdin: Stream.make(input),
+      stdout: 'pipe',
+    }).pipe(
+      spawner.spawn,
+      Effect.flatMap((child) =>
+        Effect.all(
+          {
+            exitCode: child.exitCode,
+            stderr: child.stderr.pipe(
+              Stream.decodeText,
+              Stream.mkString,
+              Effect.map((out) => out.trim()),
+            ),
+            stdout: child.stdout.pipe(Stream.decodeText, Stream.mkString),
+          },
+          { concurrency: 'unbounded' },
+        ),
+      ),
+      Effect.scoped,
+      // ⛔ ENOENT (the binary is missing) becomes the typed, named failure above — every other
+      //   PlatformError (a permission problem, a killed process) propagates as-is, still typed.
+      Effect.catchTag(
+        'PlatformError',
+        (error): Effect.Effect<never, CaddyFmtNotFound | PlatformError.PlatformError> =>
+          error.reason._tag === 'NotFound'
+            ? Effect.fail(new CaddyFmtNotFound(binaryPath, error))
+            : Effect.fail(error),
+      ),
+    );
+    if (result.exitCode !== 0) {
+      return yield* Effect.fail(new CaddyFmtFailed(binaryPath, result.exitCode, result.stderr));
+    }
+    return result.stdout;
+  });

package/src/caddy/index.ts

@@ -24,6 +24,13 @@ export { CaddyAdminService, caddyAdminLayer } from './admin.ts';
 export { isUnreachable } from './caddy-http-client.ts';
 export type { CaddyConfigAttributes, CaddyConfigProps } from './config.ts';
 export { CaddyConfig, CaddyConfigProvider } from './config.ts';
+export {
+  CaddyFmtFailed,
+  CaddyFmtNotFound,
+  DEFAULT_CADDY_BINARY,
+  formatCaddyfile,
+  type FormatCaddyfileOptions,
+} from './format.ts';
 export type { LocalCaddyAdminOptions } from './local-admin.ts';
 export { DEFAULT_ADMIN_ADDRESS, localCaddyAdmin } from './local-admin.ts';
 export { caddyProviders } from './providers.ts';

package/src/caddy/providers.test.ts

@@ -224,13 +224,21 @@ describe('the barrel', () => {
       'CaddyAdminService',
       'CaddyConfig',
       'CaddyConfigProvider',
+      // The two typed failures formatCaddyfile() can raise — see format.ts.
+      'CaddyFmtFailed',
+      'CaddyFmtNotFound',
       'DEFAULT_ADMIN_ADDRESS',
+      // `caddy` resolved on PATH, unless formatCaddyfile()'s caller points at a build — format.ts.
+      'DEFAULT_CADDY_BINARY',
       // Caddyfile TEXT for an Access-protected route, not a resource — see
       // access-forward-auth.ts. It pairs with @homeflare/cloudflare/access-auth.
       'accessForwardAuth',
       'caddyAdminLayer',
       'caddyProviders',
       'caddyWithFile',
+      // `caddy fmt -`, piped through the local binary — see format.ts's module doc for why this
+      // is never a TS reimplementation and never belongs in @distilled.cloud/caddy.
+      'formatCaddyfile',
       // The type guard config.ts's plan-time escape hatch narrows unreachable failures with —
       // exported so a consumer's own transport (an SSH forward, a remote runner) can reuse it.
       'isUnreachable',

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

@@ -0,0 +1,103 @@
+/**
+ * `Discord.ApplicationCommand`'s `spec` (global scope) against a fake Discord. Shares its engine
+ * (`discordOperations`) and its comparison functions (`command-form.ts`) with
+ * `guild-application-command.test.ts`, which covers those in depth — this file proves only what
+ * differs for global commands: the URL shape (no `guild_id`), and that `spec.attributes` never
+ * invents one.
+ */
+import { describe, expect, test } from 'bun:test';
+import type * as command from '@distilled.cloud/discord/discord';
+import * as Effect from 'effect/Effect';
+import { spec } from './application-command.ts';
+import type { ApplicationCommandProps } from './application-command.ts';
+import { fakeDiscord, fakeDiscordLayer, fakeFailure } from './fake-discord.ts';
+import { discordOperations } from './resource.ts';
+
+const APP = '111111111111111111';
+const CMD_PATH = `/applications/${APP}/commands`;
+const PROPS: ApplicationCommandProps = {
+  applicationId: APP,
+  description: 'ping the bot',
+  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',
+    id: '999',
+    name: 'ping',
+    nsfw: false,
+    type: 1,
+    version: '1',
+    ...overrides,
+  }) as unknown as command.ApplicationCommandResponse;
+
+describe('Discord.ApplicationCommand spec.fetchByName', () => {
+  test('lists the GLOBAL path, with no guild segment', async () => {
+    const fake = fakeDiscord((method, url) =>
+      method === 'GET' && url.pathname === CMD_PATH
+        ? Response.json([liveCommand()])
+        : 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]?.path).toBe(CMD_PATH);
+  });
+});
+
+describe('Discord.ApplicationCommand spec.attributes', () => {
+  test('has no guildId field at all — a global command is scopeless', () => {
+    const attrs = spec.attributes(liveCommand());
+    expect('guildId' in attrs).toBe(false);
+    expect(attrs.applicationId).toBe(APP);
+  });
+});
+
+describe('discordOperations(spec).reconcile', () => {
+  test('creates against the global path when absent', 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);
+    const attrs = await Effect.runPromise(
+      ops.reconcile(PROPS).pipe(Effect.provide(fakeDiscordLayer(fake.fetch))),
+    );
+    expect(attrs.commandId).toBe('999');
+    expect(fake.seen.some((s) => s.method === 'POST' && s.path === CMD_PATH)).toBe(true);
+  });
+
+  test('a matching live command makes zero write calls (S10)', async () => {
+    const fake = fakeDiscord((method, url) =>
+      method === 'GET' && url.pathname === CMD_PATH
+        ? Response.json([liveCommand()])
+        : fakeFailure(500, 0, 'unexpected write'),
+    );
+    const ops = discordOperations(spec);
+    await Effect.runPromise(
+      ops.reconcile(PROPS).pipe(Effect.provide(fakeDiscordLayer(fake.fetch))),
+    );
+    expect(fake.seen).toHaveLength(1);
+    expect(fake.seen[0]?.method).toBe('GET');
+  });
+});
+
+describe('discordOperations(spec).destroy', () => {
+  test('deletes against the global path by command 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);
+  });
+});

package/src/discord/application-command.ts

@@ -0,0 +1,109 @@
+/**
+ * `Discord.ApplicationCommand` — one GLOBAL slash/user/message command on a Discord application.
+ *
+ * ⛔ NOT WHAT `hf-discord-halibut.service` USES TODAY. Halibut registers guild-scoped commands
+ *   only (`DISCORD_GUILD_ID` is always set in production — see `docs/discord.md#halibut`), so this
+ *   resource has no live object to adopt yet. It exists because the distilled SDK, and Discord's
+ *   own API, model global and guild commands as siblings (same shape, different scope), and a
+ *   future bot or a future Halibut command that goes global needs it without a second family.
+ *
+ * ⚠️ GLOBAL COMMAND CHANGES TAKE UP TO AN HOUR TO PROPAGATE (Discord's own docs). A `diff` that
+ *   ran right after a write could see stale results; this resource does not poll for propagation
+ *   (S26 bounds waits at ~60s, an hour is not boundable), so a plan run inside that window may
+ *   report drift that will resolve itself. Documented, not solved — see `docs/discord.md`.
+ */
+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 ApplicationCommandProps extends CommandFields {
+  /** The Discord application (bot) this command belongs to — a public snowflake, not a secret. */
+  applicationId: string;
+}
+
+export interface ApplicationCommandAttributes extends CommandFieldsAttributes {
+  commandId: string;
+  applicationId: string;
+  version: string;
+}
+
+export interface DiscordApplicationCommand extends Resource<
+  'Discord.ApplicationCommand',
+  ApplicationCommandProps,
+  ApplicationCommandAttributes,
+  never,
+  DiscordRequirements
+> {}
+
+export const DiscordApplicationCommand = Resource<DiscordApplicationCommand>(
+  'Discord.ApplicationCommand',
+  {
+    // Commands are the thing a user reads; nothing here can be edited into another object.
+    defaultRemovalPolicy: 'retain',
+  },
+);
+
+export const isDiscordApplicationCommand = (value: unknown): value is DiscordApplicationCommand =>
+  typeof value === 'object' &&
+  value !== null &&
+  (value as { Type?: unknown }).Type === 'Discord.ApplicationCommand';
+
+const attributesOf = (live: command.ApplicationCommandResponse): ApplicationCommandAttributes => ({
+  applicationId: live.application_id,
+  commandId: live.id,
+  version: live.version,
+  ...commandFieldsOf(live),
+});
+
+/** Exported for direct testing against `fake-discord.ts` — the same seam `../netbox/prefix.ts` uses. */
+export const spec: DiscordSpec<
+  ApplicationCommandProps,
+  command.ApplicationCommandResponse,
+  ApplicationCommandAttributes,
+  DiscordOpError
+> = {
+  attributes: attributesOf,
+  describe: (props) => `applications/${props.applicationId}/commands ${props.name}`,
+  destroy: (props, live) =>
+    command.deleteApplicationCommand({ application_id: props.applicationId, command_id: live.id }),
+  fetchByName: (props) =>
+    command
+      .listApplicationCommands({ application_id: props.applicationId })
+      .pipe(Effect.map((rows) => rows.find((row) => row.name === props.name))),
+  matches: commandMatches,
+  upsert: (props, body) =>
+    command.createApplicationCommand({
+      application_id: props.applicationId,
+      ...(body as Omit<command.CreateApplicationCommandRequest, 'application_id'>),
+    }),
+  upsertBody: commandBody,
+};
+
+export const handlers = discordHandlers(spec);
+
+export const DiscordApplicationCommandProvider = () =>
+  Provider.effect(
+    DiscordApplicationCommand,
+    Effect.succeed(DiscordApplicationCommand.Provider.of(handlers)),
+  );
+
+/**
+ * `applicationCommand('help', { applicationId, name: 'help', description: '…' })` — `adopt(true)`
+ *   piped on by default (H5), so a first deploy against a command that already exists silently
+ *   takes it over instead of failing `OwnedBySomeoneElse`. Mirrors `cloudflare/website.ts`'s
+ *   `astroWebsite`/`viteWebsite` convenience constructors.
+ */
+export const applicationCommand = (id: string, props: ApplicationCommandProps) =>
+  DiscordApplicationCommand(id, props).pipe(adopt(true));

package/src/discord/command-form.test.ts

@@ -0,0 +1,144 @@
+/**
+ * `command-form.ts`'s pure functions — no server, no Effect runtime, the same shape
+ * `../netbox/prefix-form.test.ts` uses for `prefixBody`/`prefixMatches`.
+ */
+import { describe, expect, test } from 'bun:test';
+import {
+  type CommandFields,
+  type CommandFieldsAttributes,
+  commandBody,
+  commandFieldsOf,
+  commandMatches,
+} from './command-form.ts';
+
+describe('commandBody', () => {
+  test('settles description/nsfw/type when undeclared, the way Discord itself would', () => {
+    expect(commandBody({ name: 'ping' })).toEqual({
+      description: '',
+      name: 'ping',
+      nsfw: false,
+      type: 1,
+    });
+  });
+
+  test('an omitted field is left OUT of the body, never sent empty/null/false', () => {
+    const body = commandBody({ name: 'ping' });
+    expect(Object.prototype.hasOwnProperty.call(body, 'options')).toBe(false);
+    expect(Object.prototype.hasOwnProperty.call(body, 'default_member_permissions')).toBe(false);
+    expect(Object.prototype.hasOwnProperty.call(body, 'dm_permission')).toBe(false);
+    expect(Object.prototype.hasOwnProperty.call(body, 'contexts')).toBe(false);
+    expect(Object.prototype.hasOwnProperty.call(body, 'integration_types')).toBe(false);
+  });
+
+  test('every declared field reaches the wire body under its wire name', () => {
+    const props: CommandFields = {
+      contexts: [0, 1],
+      defaultMemberPermissions: '2147483648',
+      description: 'ping the bot',
+      dmPermission: false,
+      integrationTypes: [0],
+      name: 'ping',
+      nsfw: true,
+      options: [{ name: 'loud', type: 5 }],
+      type: 1,
+    };
+    expect(commandBody(props)).toEqual({
+      contexts: [0, 1],
+      default_member_permissions: '2147483648',
+      description: 'ping the bot',
+      dm_permission: false,
+      integration_types: [0],
+      name: 'ping',
+      nsfw: true,
+      options: [{ name: 'loud', type: 5 }],
+      type: 1,
+    });
+  });
+});
+
+const attrsOf = (overrides: Partial<CommandFieldsAttributes> = {}): CommandFieldsAttributes => ({
+  contexts: undefined,
+  defaultMemberPermissions: undefined,
+  description: '',
+  dmPermission: undefined,
+  integrationTypes: undefined,
+  name: 'ping',
+  nsfw: false,
+  options: [],
+  type: 1,
+  ...overrides,
+});
+
+describe('commandMatches', () => {
+  test('an exact match reports no drift', () => {
+    expect(commandMatches(attrsOf(), { name: 'ping' })).toBe(true);
+  });
+
+  test('a description change is drift', () => {
+    expect(
+      commandMatches(attrsOf({ description: 'old' }), { description: 'new', name: 'ping' }),
+    ).toBe(false);
+  });
+
+  test('a name change is drift — name is part of identity but still compared', () => {
+    expect(commandMatches(attrsOf({ name: 'ping' }), { name: 'pong' })).toBe(false);
+  });
+
+  test('options are compared by deep equality, order included', () => {
+    const live = attrsOf({ options: [{ name: 'a' }, { name: 'b' }] });
+    expect(commandMatches(live, { name: 'ping', options: [{ name: 'a' }, { name: 'b' }] })).toBe(
+      true,
+    );
+    expect(commandMatches(live, { name: 'ping', options: [{ name: 'b' }, { name: 'a' }] })).toBe(
+      false,
+    );
+  });
+
+  test('an undeclared optional field is not compared — "not mine", both directions', () => {
+    const live = attrsOf({ defaultMemberPermissions: '8', dmPermission: true });
+    expect(commandMatches(live, { name: 'ping' })).toBe(true);
+  });
+
+  /**
+   * 🔴 THE CASE THAT SHIPPED WRONG ONCE (caught in review, before merge — not measured live).
+   *   `options` must be gated exactly like every other optional field above: a declaration with
+   *   no `options` at all reports no drift against a live command that has some, because
+   *   `commandBody` already omits `options` when undeclared — comparing unconditionally would
+   *   report drift no write could ever fix (an infinite "update"), and worse, the first real
+   *   (non-dry-run) deploy would send a body with no `options` key, and Discord's real
+   *   full-replace create would wipe the live command's arguments.
+   */
+  test('undeclared options against a live command that HAS options is not drift', () => {
+    const live = attrsOf({ options: [{ name: 'loud', type: 5 }] });
+    expect(commandMatches(live, { name: 'ping' })).toBe(true);
+  });
+
+  test('a declared optional field that disagrees with live is drift', () => {
+    const live = attrsOf({ defaultMemberPermissions: '8' });
+    expect(commandMatches(live, { defaultMemberPermissions: '16', name: 'ping' })).toBe(false);
+  });
+});
+
+describe('commandFieldsOf', () => {
+  test('reads every field off an ApplicationCommandResponse-shaped object, null coerced to undefined', () => {
+    expect(
+      commandFieldsOf({
+        contexts: null,
+        default_member_permissions: null,
+        description: 'ping the bot',
+        dm_permission: undefined,
+        integration_types: undefined,
+        name: 'ping',
+        nsfw: undefined,
+        options: null,
+        type: 1,
+      }),
+    ).toEqual(attrsOf({ description: 'ping the bot' }));
+  });
+
+  test('nsfw is strictly `=== true`, never truthy-coerced', () => {
+    expect(commandFieldsOf({ description: '', name: 'x', nsfw: undefined, type: 1 }).nsfw).toBe(
+      false,
+    );
+  });
+});