@homeflare/alchemy 0.36.0 → 0.37.1

package/src/argocd/repo-creds.ts

@@ -0,0 +1,115 @@
+/**
+ * `Argocd.RepoCreds` — a credential TEMPLATE that Argo CD applies to any repository whose URL
+ * starts with `url` (`/api/v1/repocreds`) — distinct from `Argocd.Repository`, which registers one
+ * specific repository. REST-managed, not a CRD; see `docs/argocd.md`.
+ *
+ * ⚠️ NO `GetRepoCredsService` OPERATION EXISTS — measured against the operation list in
+ *   `services/argocd.ts` (distilled homeflare/base): Create/Update/Delete/List only, no single-item
+ *   Get. `fetchLive` below lists and finds by `url`, the same shape
+ *   `discord/guild-application-command.ts#fetchByName` and
+ *   `forgejo/org-actions-secrets.ts#fetchLive` use for the same reason.
+ *
+ * ⚠️ NO LIVE ARGO CD INSTANCE EXISTS ON THE ESTATE (2026-09-24) — see `docs/argocd.md`.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as argocd from '@distilled.cloud/argocd/argocd';
+import * as Effect from 'effect/Effect';
+import {
+  type ArgocdSecretEnvUnsetError,
+  type GitCredentialRefs,
+  resolveGitCredentials,
+} from './git-credentials.ts';
+import { type ArgocdRequirements, type ArgocdSpec, argocdHandlers, present } from './resource.ts';
+
+export interface RepoCredsProps {
+  /** The URL prefix this template matches — identity key; changing it is a replace. */
+  url: string;
+  /** "git" (default), "helm" or "oci". */
+  type?: string;
+  username?: string;
+  /** The client certificate itself — public, unlike its key. */
+  tlsClientCertData?: string;
+  /** Write-only — see `git-credentials.ts`. Never a value here, only env var names. */
+  credentials?: GitCredentialRefs;
+}
+
+export interface RepoCredsAttributes {
+  url: string;
+  type: string | undefined;
+  username: string | undefined;
+  tlsClientCertData: string | undefined;
+}
+
+export interface ArgocdRepoCreds extends Resource<
+  'Argocd.RepoCreds',
+  RepoCredsProps,
+  RepoCredsAttributes,
+  never,
+  ArgocdRequirements
+> {}
+
+export const ArgocdRepoCreds = Resource<ArgocdRepoCreds>('Argocd.RepoCreds');
+
+const attributesOf = (live: argocd.V1alpha1RepoCreds): RepoCredsAttributes => ({
+  tlsClientCertData: live.tlsClientCertData,
+  type: live.type,
+  url: live.url ?? '',
+  username: live.username,
+});
+
+/** Only the plain fields — see `git-credentials.ts` for why the secret fields are excluded. */
+const plainMatches = (attrs: RepoCredsAttributes, props: RepoCredsProps): boolean =>
+  (props.type ?? 'git') === (attrs.type ?? 'git') &&
+  (props.username ?? undefined) === (attrs.username ?? undefined) &&
+  (props.tlsClientCertData ?? undefined) === (attrs.tlsClientCertData ?? undefined);
+
+type RepoCredsError =
+  | argocd.ListRepoCredsServiceRepositoryCredentialsError
+  | argocd.CreateRepoCredsServiceRepositoryCredentialsError
+  | argocd.DeleteRepoCredsServiceRepositoryCredentialsError
+  | ArgocdSecretEnvUnsetError;
+
+/** ★ EXPORTED for direct testing against `fake-argocd.ts` — see `repo-creds.test.ts`. */
+export const spec: ArgocdSpec<
+  RepoCredsProps,
+  argocd.V1alpha1RepoCreds,
+  RepoCredsAttributes,
+  RepoCredsError
+> = {
+  attributes: (live) => attributesOf(live),
+  // ★ Catches the DELETE call's own NotFound too — closes the TOCTOU race between the pre-check
+  //   `fetchLive` above and this call. Matches upstream's Hetzner/Certificate.ts `deleteById`.
+  destroy: (props) =>
+    argocd
+      .deleteRepoCredsServiceRepositoryCredentials({ url: props.url })
+      .pipe(Effect.catchTag('NotFound', () => Effect.void)),
+  identityOfAttributes: (attrs) => attrs.url,
+  identityOfProps: (props) => props.url,
+  fetchLive: (props) =>
+    argocd.listRepoCredsServiceRepositoryCredentials({ url: props.url }).pipe(
+      Effect.map((page) => (page.items ?? []).find((row) => row.url === props.url)),
+      Effect.catchTag('NotFound', () => Effect.succeed(undefined)),
+    ),
+  matches: plainMatches,
+  upsert: (props) =>
+    resolveGitCredentials(props.credentials ?? {}).pipe(
+      Effect.flatMap((creds) =>
+        argocd.createRepoCredsServiceRepositoryCredentials(
+          present({
+            upsert: true,
+            tlsClientCertData: props.tlsClientCertData,
+            type: props.type,
+            url: props.url,
+            username: props.username,
+            ...creds,
+          }),
+        ),
+      ),
+    ),
+};
+
+export const handlers = argocdHandlers(spec);
+
+export const ArgocdRepoCredsProvider = () =>
+  Provider.effect(ArgocdRepoCreds, Effect.succeed(ArgocdRepoCreds.Provider.of(handlers)));

package/src/argocd/repository.test.ts

@@ -0,0 +1,167 @@
+/**
+ * `Argocd.Repository`'s `spec` against a fake Argo CD — proves the doctrine-required shapes:
+ *
+ * - `fetchLive` folds a real distilled `NotFound` (404) to `undefined`, and does NOT fold a
+ *   401 — the same `catchTag('NotFound', ...)` idiom `forgejo/repository.test.ts` proves.
+ * - `spec.destroy`-via-`argocdOperations#destroy` is idempotent: a delete of an already-absent
+ *   repository makes no request at all (S11).
+ * - `spec.upsert` sends `upsert: true` and resolves write-only credentials from the environment,
+ *   never a literal value on a stack file — and refuses (a typed domain error, not a distilled
+ *   one) when the declared env var is unset.
+ *
+ * No live Argo CD instance exists on the estate (2026-09-24) — every assertion here runs against
+ * `fake-argocd.ts`, never a real server.
+ */
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { FAKE_BASE, fakeArgocd, fakeArgocdLayer, fakeFailure } from './fake-argocd.ts';
+import { argocdOperations } from './resource.ts';
+import { spec } from './repository.ts';
+
+const REPO = `${FAKE_BASE}/homeflare/kit.git`;
+const ENV_VAR = 'ARGOCD_REPO_KIT_PASSWORD';
+
+const liveRepo = (overrides: Record<string, unknown> = {}) =>
+  Response.json({ enableLfs: true, repo: REPO, type: 'git', ...overrides });
+
+describe('Argocd.Repository spec.fetchLive', () => {
+  test('a live repository decodes into attributes', async () => {
+    const fake = fakeArgocd((method) =>
+      method === 'GET' ? liveRepo() : fakeFailure(404, 'not found'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive({ repo: REPO }).pipe(Effect.provide(fakeArgocdLayer(fake.fetch))),
+    );
+    expect(live?.repo).toBe(REPO);
+    expect(live?.enableLfs).toBe(true);
+  });
+
+  test('a 404 folds to undefined', async () => {
+    const fake = fakeArgocd(() => fakeFailure(404, 'repository not found'));
+    const result = await Effect.runPromise(
+      spec.fetchLive({ repo: REPO }).pipe(Effect.provide(fakeArgocdLayer(fake.fetch))),
+    );
+    expect(result).toBeUndefined();
+  });
+
+  test('a 401 propagates — not folded to absent', async () => {
+    const fake = fakeArgocd(() => fakeFailure(401, 'bad token'));
+    const failure = await Effect.runPromise(
+      Effect.flip(spec.fetchLive({ repo: REPO }).pipe(Effect.provide(fakeArgocdLayer(fake.fetch)))),
+    );
+    expect(failure._tag).toBe('Unauthorized');
+  });
+});
+
+describe('Argocd.Repository destroy — idempotent (S11)', () => {
+  test('deleting an already-absent repository makes no delete call', async () => {
+    const fake = fakeArgocd(() => fakeFailure(404, 'repository not found'));
+    await Effect.runPromise(
+      argocdOperations(spec)
+        .destroy({ repo: REPO })
+        .pipe(Effect.provide(fakeArgocdLayer(fake.fetch))),
+    );
+    // Only the read (fetchLive) happened — never a DELETE against an object that was never there.
+    expect(fake.seen.every((call) => call.method !== 'DELETE')).toBe(true);
+  });
+
+  test('deleting a live repository calls DELETE once', async () => {
+    const fake = fakeArgocd((method) => (method === 'GET' ? liveRepo() : Response.json({})));
+    await Effect.runPromise(
+      argocdOperations(spec)
+        .destroy({ repo: REPO })
+        .pipe(Effect.provide(fakeArgocdLayer(fake.fetch))),
+    );
+    expect(fake.seen.filter((call) => call.method === 'DELETE')).toHaveLength(1);
+  });
+
+  test('the DELETE call itself returning 404 (a race with an external removal) still succeeds', async () => {
+    // ⚠️ Different from the "already-absent" case above: fetchLive's pre-check finds the object
+    //   live, but something else deletes it before this call's own DELETE lands — matching
+    //   upstream's Hetzner/Certificate.ts `deleteById` pattern (catchTag on the delete itself).
+    const fake = fakeArgocd((method) =>
+      method === 'GET' ? liveRepo() : fakeFailure(404, 'repository not found'),
+    );
+    await Effect.runPromise(
+      argocdOperations(spec)
+        .destroy({ repo: REPO })
+        .pipe(Effect.provide(fakeArgocdLayer(fake.fetch))),
+    );
+    expect(fake.seen.filter((call) => call.method === 'DELETE')).toHaveLength(1);
+  });
+});
+
+describe('Argocd.Repository spec.upsert — write-only credentials', () => {
+  beforeEach(() => {
+    delete process.env[ENV_VAR];
+  });
+  afterEach(() => {
+    delete process.env[ENV_VAR];
+  });
+
+  test('refuses with a typed domain error when the declared env var is unset', async () => {
+    const fake = fakeArgocd(() => fakeFailure(404, 'unused'));
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        spec
+          .upsert({ credentials: { password: { fromEnv: ENV_VAR } }, repo: REPO, username: 'ci' })
+          .pipe(Effect.provide(fakeArgocdLayer(fake.fetch))),
+      ),
+    );
+    expect(failure._tag).toBe('ArgocdSecretEnvUnsetError');
+    expect(fake.seen).toEqual([]);
+  });
+
+  test('resolves the env var and sends it — never the FromEnv reference itself', async () => {
+    process.env[ENV_VAR] = 'hunter2';
+    const fake = fakeArgocd((method) =>
+      method === 'POST' ? Response.json({ repo: REPO }) : fakeFailure(404, 'x'),
+    );
+    await Effect.runPromise(
+      spec
+        .upsert({ credentials: { password: { fromEnv: ENV_VAR } }, repo: REPO, username: 'ci' })
+        .pipe(Effect.provide(fakeArgocdLayer(fake.fetch))),
+    );
+    const [create] = fake.seen.filter((call) => call.method === 'POST');
+    // `upsert` is a query-string trait on this operation (`T.Query()`), not a body field —
+    // measured against `CreateRepositoryServiceRepositoryRequest` in services/argocd.ts.
+    expect(create?.path).toContain('upsert=true');
+    const body = create?.body as Record<string, unknown>;
+    expect(body.password).toBe('hunter2');
+    expect(body.username).toBe('ci');
+    expect(JSON.stringify(body)).not.toContain('fromEnv');
+  });
+});
+
+describe('Argocd.Repository diff — a changed identity key is a replace, never an update', () => {
+  // ⛔ REGRESSION: adversarial review 2026-09-24 found `diff` could only ever return
+  //   noop/update, so a changed `repo` (Argo CD indexes by it) silently created a new
+  //   registration at the new URL and left the old, still-credentialed one orphaned — no state
+  //   pointed at it, nothing would ever delete it. Fixed via `identityOfProps`/
+  //   `identityOfAttributes` in resource.ts.
+  const RENAMED_REPO = `${FAKE_BASE}/homeflare/kit-renamed.git`;
+  const oldOutput = spec.attributes({ enableLfs: true, repo: REPO, type: 'git' }, { repo: REPO });
+
+  test('a changed repo URL is a replace, and no read of the new URL happens first', async () => {
+    const fake = fakeArgocd(() => fakeFailure(500, 'must not be called — identity differs'));
+    const result = await Effect.runPromise(
+      argocdOperations(spec)
+        .diff({ repo: RENAMED_REPO }, oldOutput)
+        .pipe(Effect.provide(fakeArgocdLayer(fake.fetch))),
+    );
+    expect(result).toEqual({ action: 'replace' });
+    expect(fake.seen).toEqual([]);
+  });
+
+  test('the SAME repo URL with a plain-field change is an update, not a replace', async () => {
+    const fake = fakeArgocd((method) =>
+      method === 'GET' ? liveRepo({ enableLfs: false }) : fakeFailure(404, 'x'),
+    );
+    const result = await Effect.runPromise(
+      argocdOperations(spec)
+        .diff({ enableLfs: true, repo: REPO }, oldOutput)
+        .pipe(Effect.provide(fakeArgocdLayer(fake.fetch))),
+    );
+    expect(result).toEqual({ action: 'update' });
+  });
+});

package/src/argocd/repository.ts

@@ -0,0 +1,165 @@
+/**
+ * `Argocd.Repository` — a git/helm/OCI source registered with an Argo CD instance
+ * (`/api/v1/repositories`). REST-managed, NOT a Kubernetes CRD — see `docs/argocd.md` for the
+ * measured split between this family and `Kubernetes.Manifest` (upstream Alchemy's family, for
+ * `Application`/`AppProject`, which genuinely are CRDs).
+ *
+ * ⚠️ NO LIVE ARGO CD INSTANCE EXISTS ON THE ESTATE (2026-09-24). Built ahead of the Talos-on-PVE
+ *   cluster this targets; every test runs against `fake-argocd.ts`. See `docs/argocd.md`.
+ *
+ * ⛔ `defaultRemovalPolicy: 'retain'` — deregistering a repository Argo CD applications still
+ *   reference breaks their sync, the same reasoning `forgejo/repository.ts` gives for git repos.
+ *   `delete` below is fully implemented; opt in with `.pipe(RemovalPolicy.destroy())`.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as argocd from '@distilled.cloud/argocd/argocd';
+import * as Effect from 'effect/Effect';
+import {
+  type ArgocdSecretEnvUnsetError,
+  type GitCredentialRefs,
+  resolveGitCredentials,
+} from './git-credentials.ts';
+import { type ArgocdRequirements, type ArgocdSpec, argocdHandlers, present } from './resource.ts';
+
+export interface RepositoryProps {
+  /** The repository URL — identity key; changing it is a replace, not an update. */
+  repo: string;
+  /** "git" (default), "helm" or "oci". */
+  type?: string;
+  /** Required for "helm" repositories (Argo CD indexes helm repos by name, not URL). */
+  name?: string;
+  /** Restricts this repository to one Argo CD project; omit for every project. */
+  project?: string;
+  username?: string;
+  insecure?: boolean;
+  insecureIgnoreHostKey?: boolean;
+  enableLfs?: boolean;
+  enableOCI?: boolean;
+  forceHttpBasicAuth?: boolean;
+  proxy?: string;
+  noProxy?: string;
+  /** The client certificate itself — public, unlike its key. */
+  tlsClientCertData?: string;
+  /** Write-only — see `git-credentials.ts`. Never a value here, only env var names. */
+  credentials?: GitCredentialRefs;
+}
+
+export interface RepositoryAttributes {
+  repo: string;
+  type: string | undefined;
+  name: string | undefined;
+  project: string | undefined;
+  username: string | undefined;
+  insecure: boolean | undefined;
+  insecureIgnoreHostKey: boolean | undefined;
+  enableLfs: boolean | undefined;
+  enableOCI: boolean | undefined;
+  forceHttpBasicAuth: boolean | undefined;
+  proxy: string | undefined;
+  noProxy: string | undefined;
+  tlsClientCertData: string | undefined;
+}
+
+export interface ArgocdRepository extends Resource<
+  'Argocd.Repository',
+  RepositoryProps,
+  RepositoryAttributes,
+  never,
+  ArgocdRequirements
+> {}
+
+export const ArgocdRepository = Resource<ArgocdRepository>('Argocd.Repository', {
+  defaultRemovalPolicy: 'retain',
+});
+
+const attributesOf = (live: argocd.V1alpha1Repository): RepositoryAttributes => ({
+  enableLfs: live.enableLfs,
+  enableOCI: live.enableOCI,
+  forceHttpBasicAuth: live.forceHttpBasicAuth,
+  insecure: live.insecure,
+  insecureIgnoreHostKey: live.insecureIgnoreHostKey,
+  name: live.name,
+  noProxy: live.noProxy,
+  project: live.project,
+  proxy: live.proxy,
+  repo: live.repo ?? '',
+  tlsClientCertData: live.tlsClientCertData,
+  type: live.type,
+  username: live.username,
+});
+
+/** Only the plain fields — see `git-credentials.ts` for why the secret fields are excluded. */
+const plainMatches = (attrs: RepositoryAttributes, props: RepositoryProps): boolean =>
+  (props.type ?? 'git') === (attrs.type ?? 'git') &&
+  (props.name ?? undefined) === (attrs.name ?? undefined) &&
+  (props.project ?? undefined) === (attrs.project ?? undefined) &&
+  (props.username ?? undefined) === (attrs.username ?? undefined) &&
+  Boolean(props.insecure) === Boolean(attrs.insecure) &&
+  Boolean(props.insecureIgnoreHostKey) === Boolean(attrs.insecureIgnoreHostKey) &&
+  Boolean(props.enableLfs) === Boolean(attrs.enableLfs) &&
+  Boolean(props.enableOCI) === Boolean(attrs.enableOCI) &&
+  Boolean(props.forceHttpBasicAuth) === Boolean(attrs.forceHttpBasicAuth) &&
+  (props.proxy ?? undefined) === (attrs.proxy ?? undefined) &&
+  (props.noProxy ?? undefined) === (attrs.noProxy ?? undefined) &&
+  (props.tlsClientCertData ?? undefined) === (attrs.tlsClientCertData ?? undefined);
+
+type RepositoryError =
+  | argocd.GetRepositoryServiceError
+  | argocd.CreateRepositoryServiceRepositoryError
+  | argocd.DeleteRepositoryServiceRepositoryError
+  | ArgocdSecretEnvUnsetError;
+
+/** ★ EXPORTED for direct testing against `fake-argocd.ts` — see `repository.test.ts`. */
+export const spec: ArgocdSpec<
+  RepositoryProps,
+  argocd.V1alpha1Repository,
+  RepositoryAttributes,
+  RepositoryError
+> = {
+  attributes: (live) => attributesOf(live),
+  // ★ Catches the DELETE call's own NotFound too, not just the pre-check `fetchLive` fold above
+  //   — closes the TOCTOU race between that read and this call (the object could be removed by
+  //   something else in between). Matches upstream's own pattern: Hetzner/Certificate.ts's
+  //   `deleteById` (`.pipe(Effect.catchTag('NotFound', () => Effect.void))`).
+  destroy: (props) =>
+    argocd
+      .deleteRepositoryServiceRepository({ repo: props.repo })
+      .pipe(Effect.catchTag('NotFound', () => Effect.void)),
+  identityOfAttributes: (attrs) => attrs.repo,
+  identityOfProps: (props) => props.repo,
+  fetchLive: (props) =>
+    argocd
+      .getRepositoryService({ repo: props.repo })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+  matches: plainMatches,
+  upsert: (props) =>
+    resolveGitCredentials(props.credentials ?? {}).pipe(
+      Effect.flatMap((creds) =>
+        argocd.createRepositoryServiceRepository(
+          present({
+            upsert: true,
+            enableLfs: props.enableLfs,
+            enableOCI: props.enableOCI,
+            forceHttpBasicAuth: props.forceHttpBasicAuth,
+            insecure: props.insecure,
+            insecureIgnoreHostKey: props.insecureIgnoreHostKey,
+            name: props.name,
+            noProxy: props.noProxy,
+            project: props.project,
+            proxy: props.proxy,
+            repo: props.repo,
+            tlsClientCertData: props.tlsClientCertData,
+            type: props.type,
+            username: props.username,
+            ...creds,
+          }),
+        ),
+      ),
+    ),
+};
+
+export const handlers = argocdHandlers(spec);
+
+export const ArgocdRepositoryProvider = () =>
+  Provider.effect(ArgocdRepository, Effect.succeed(ArgocdRepository.Provider.of(handlers)));

package/src/argocd/resource.ts

@@ -0,0 +1,150 @@
+/**
+ * One shape for every Argo CD REST object — Repository, RepoCreds, Cluster — the same four
+ * operations, different distilled call.
+ *
+ * ⛔ THIS IS A NEAR-VERBATIM COPY OF `../forgejo/resource.ts`'S ENGINE, ON PURPOSE. Both SDKs speak
+ *   plain bearer-authenticated REST with a real `NotFound` tag (see the family's own docs.md for
+ *   why Argo CD, UNLIKE Discord, gets a genuine typed 404 — measured from `protocol.ts`), so the
+ *   same read/diff/reconcile/destroy shape applies unchanged. A second hand-rolled engine here
+ *   would just be forgejo's with the names swapped.
+ *
+ * ⚠️ NO `Unowned`/`adopt(true)` WRAPPING HERE — mirrors forgejo's own choice (not netbox's or
+ *   discord's `Unowned` marker), not an oversight. A live match on a cold read (no persisted
+ *   `output`) is treated as ours, same as every other forgejo-shaped family in this kit today.
+ *
+ * ⚠️ `NotFound` IS FOLDED TO "ABSENT" INSIDE EACH RESOURCE FILE'S OWN `fetchLive`, NOT HERE.
+ *   `Effect.catchTag`'s tag-literal inference needs a concrete error union to resolve `"NotFound"`
+ *   against; a spec's `E` is only concrete at each resource file's own call site. So every
+ *   `fetchLive` ends `.pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined)))` itself.
+ */
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import { CredentialsFromEnv } from '@distilled.cloud/argocd/Credentials';
+import type { ArgocdOpContext } from '@distilled.cloud/argocd/Protocol';
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+
+/** What every handler needs from the caller's runtime, once `argocdHandlers` bakes in credentials. */
+export type ArgocdRequirements = HttpClient.HttpClient;
+
+/**
+ * Strips undefined-valued keys, mapping each to a genuinely optional key rather than a present
+ * key typed `X | undefined`. `tsconfig.base.json` turns on `exactOptionalPropertyTypes`, and every
+ * generated Argo CD request type declares its optional fields the strict way (`foo?: X`, never
+ * `foo?: X | undefined`) — so `{ foo: props.foo }` where `props.foo?: X` does not typecheck against
+ * it even when `foo` is genuinely absent at runtime. Every resource file's request body goes
+ * through this once, mirroring `forgejo/repository.ts#editForm`'s conditional-spread idiom, just
+ * generalized instead of repeated per field.
+ */
+export const present = <T extends object>(obj: T): { [K in keyof T]?: Exclude<T[K], undefined> } =>
+  Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined)) as never;
+
+/**
+ * One Argo CD object's distilled calls. `Live` is whatever the SDK decodes (`V1alpha1Repository`,
+ * `V1alpha1Cluster`, …); `E` is left to each resource file to declare.
+ */
+export type ArgocdSpec<Props extends object, Live, Attributes, E> = {
+  /**
+   * The identity key's value — `repo`/`url`/`server` depending on the resource — read off
+   * declared props and off persisted attributes respectively. `diff` compares the two to detect
+   * an identity change, which `upsert`'s single create-or-converge call cannot express as an
+   * in-place update: Argo CD indexes each of these objects BY this value, so a changed identity
+   * means a create at the new key, never a rename, and the object left at the old key must be
+   * deleted — exactly what a `replace` diff action tells Alchemy's own Plan/Apply to do (delete
+   * the old physical object, using `olds`, then reconcile `news`). Without this, a changed
+   * `repo`/`url`/`server` orphans the old, still-credentialed object with no state pointing at it
+   * — found in adversarial review 2026-09-24, fixed here.
+   */
+  readonly identityOfProps: (props: Props) => string;
+  readonly identityOfAttributes: (attributes: Attributes) => string;
+  /** Already folds the SDK's `NotFound` to `undefined` via its own `catchTag` — see the note above. */
+  readonly fetchLive: (props: Props) => Effect.Effect<Live | undefined, E, ArgocdOpContext>;
+  readonly attributes: (live: Live, props: Props) => Attributes | undefined;
+  readonly matches: (attributes: Attributes, props: Props) => boolean;
+  /**
+   * A single upsert call — every Argo CD create endpoint this family uses takes `upsert: true`
+   * and converges create-or-update in one request, so there is no separate update path to wire.
+   */
+  readonly upsert: (props: Props) => Effect.Effect<unknown, E, ArgocdOpContext>;
+  readonly destroy: (props: Props, live: Live) => Effect.Effect<unknown, E, ArgocdOpContext>;
+};
+
+export const argocdOperations = <Props extends object, Live, Attributes, E>(
+  spec: ArgocdSpec<Props, Live, Attributes, E>,
+) => {
+  const read = (props: Props) =>
+    spec
+      .fetchLive(props)
+      .pipe(Effect.map((live) => (live === undefined ? undefined : spec.attributes(live, props))));
+
+  return {
+    read,
+
+    diff: (news: Input<Props>, output: Attributes | undefined) =>
+      Effect.gen(function* () {
+        if (output === undefined || !isResolved(news)) return undefined;
+        // The identity key changed (repo/url/server) — `upsert` cannot rename in place, it would
+        // create at the new key and leave the old, still-live object orphaned. See the spec type.
+        if (spec.identityOfProps(news) !== spec.identityOfAttributes(output)) {
+          return { action: 'replace' } as const;
+        }
+        const live = yield* read(news);
+        if (live === undefined) return { action: 'update' } as const;
+        return spec.matches(live, news)
+          ? ({ action: 'noop' } as const)
+          : ({ action: 'update' } as const);
+      }),
+
+    reconcile: (news: Props) =>
+      Effect.gen(function* () {
+        const before = yield* read(news);
+        // S10: no write when what's declared already matches what's live.
+        if (before === undefined || !spec.matches(before, news)) {
+          yield* spec.upsert(news);
+        }
+        const after = yield* read(news);
+        if (after === undefined) {
+          return yield* Effect.die(
+            new Error(
+              'the write returned no error but the object is still absent — read back rather ' +
+                'than trust the status code.',
+            ),
+          );
+        }
+        return after;
+      }),
+
+    destroy: (olds: Props) =>
+      Effect.gen(function* () {
+        const live = yield* spec.fetchLive(olds);
+        if (live === undefined) return;
+        yield* spec.destroy(olds, live);
+      }),
+  };
+};
+
+/**
+ * The four provider handlers for a spec'd Argo CD object, wired once.
+ *
+ * ★ CREDENTIALS ARE PROVIDED HERE, ONCE. `CredentialsFromEnv` resolves `ARGOCD_TOKEN` /
+ *   `ARGOCD_SERVER` on the calling fiber per request (credentials.ts), never captured at load.
+ *
+ * ⚠️ `list` answers empty — Argo CD's list endpoints return every object of that kind on the whole
+ *   instance; adoption stays explicit (a declared resource's own `read`), same reasoning as
+ *   forgejo and discord.
+ */
+export const argocdHandlers = <Props extends object, Live, Attributes extends object, E>(
+  spec: ArgocdSpec<Props, Live, Attributes, E>,
+) => {
+  const ops = argocdOperations(spec);
+  const withCredentials = <A>(effect: Effect.Effect<A, E, ArgocdOpContext>) =>
+    Effect.provide(effect, CredentialsFromEnv);
+  return {
+    list: () => Effect.succeed([]),
+    read: ({ olds }: { olds: Props }) => withCredentials(ops.read(olds)),
+    diff: ({ news, output }: { news: Input<Props>; output: Attributes | undefined }) =>
+      withCredentials(ops.diff(news, output)),
+    reconcile: ({ news }: { news: Props }) => withCredentials(ops.reconcile(news)),
+    delete: ({ olds }: { olds: Props }) => withCredentials(ops.destroy(olds)),
+  };
+};