@homeflare/alchemy 0.35.0 → 0.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.35.0",
+  "version": "0.37.0",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
@@ -28,6 +28,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./argocd": {
+      "types": "./dist/argocd/index.d.ts",
+      "default": "./dist/argocd/index.js"
+    },
     "./cloudflare": {
       "types": "./dist/cloudflare/index.d.ts",
       "default": "./dist/cloudflare/index.js"
@@ -120,11 +124,12 @@
     "@distilled.cloud/netbox": "npm:@homeflare/distilled-netbox@0.3.0",
     "@distilled.cloud/opnsense": "npm:@homeflare/distilled-opnsense@0.2.0",
     "@distilled.cloud/paperless-ngx": "npm:@homeflare/distilled-paperless-ngx@0.3.0",
-    "@distilled.cloud/proxmox": "npm:@homeflare/distilled-proxmox@0.2.0",
-    "@distilled.cloud/proxmox-backup": "npm:@homeflare/distilled-proxmox-backup@0.2.0",
+    "@distilled.cloud/proxmox": "npm:@homeflare/distilled-proxmox@0.3.0",
+    "@distilled.cloud/proxmox-backup": "npm:@homeflare/distilled-proxmox-backup@0.3.0",
     "@distilled.cloud/unifi-network": "npm:@homeflare/distilled-unifi-network@0.2.0"
   },
   "peerDependencies": {
+    "@distilled.cloud/argocd": "1.0.0-rc.12",
     "@distilled.cloud/cloudflare": "1.0.0-rc.12",
     "@distilled.cloud/discord": "1.0.0-rc.12",
     "@distilled.cloud/forgejo": "1.0.0-rc.12",

package/src/argocd/cluster.test.ts

@@ -0,0 +1,120 @@
+/**
+ * `Argocd.Cluster`'s `spec` against a fake Argo CD — the same three doctrine-required shapes as
+ * `repository.test.ts`, plus the nested `config.tlsClientConfig` credential path.
+ */
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { fakeArgocd, fakeArgocdLayer, fakeFailure } from './fake-argocd.ts';
+import { argocdOperations } from './resource.ts';
+import { spec } from './cluster.ts';
+
+const SERVER = 'https://talos.example.com:6443';
+const ENV_VAR = 'ARGOCD_CLUSTER_TALOS_BEARER_TOKEN';
+
+const liveCluster = (overrides: Record<string, unknown> = {}) =>
+  Response.json({ name: 'talos', server: SERVER, ...overrides });
+
+describe('Argocd.Cluster spec.fetchLive', () => {
+  test('a live cluster decodes into attributes, including nested tls config', async () => {
+    const fake = fakeArgocd((method) =>
+      method === 'GET'
+        ? liveCluster({
+            config: { tlsClientConfig: { insecure: false, serverName: 'talos.internal' } },
+          })
+        : fakeFailure(404, 'not found'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive({ server: SERVER }).pipe(Effect.provide(fakeArgocdLayer(fake.fetch))),
+    );
+    expect(live?.server).toBe(SERVER);
+    expect(live?.config?.tlsClientConfig?.serverName).toBe('talos.internal');
+  });
+
+  test('a 404 folds to undefined', async () => {
+    const fake = fakeArgocd(() => fakeFailure(404, 'cluster not found'));
+    const result = await Effect.runPromise(
+      spec.fetchLive({ server: SERVER }).pipe(Effect.provide(fakeArgocdLayer(fake.fetch))),
+    );
+    expect(result).toBeUndefined();
+  });
+
+  test('a 403 propagates — not folded to absent', async () => {
+    const fake = fakeArgocd(() => fakeFailure(403, 'forbidden'));
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        spec.fetchLive({ server: SERVER }).pipe(Effect.provide(fakeArgocdLayer(fake.fetch))),
+      ),
+    );
+    expect(failure._tag).toBe('Forbidden');
+  });
+});
+
+describe('Argocd.Cluster destroy — idempotent (S11)', () => {
+  test('deleting an already-absent cluster makes no DELETE call', async () => {
+    const fake = fakeArgocd(() => fakeFailure(404, 'cluster not found'));
+    await Effect.runPromise(
+      argocdOperations(spec)
+        .destroy({ server: SERVER })
+        .pipe(Effect.provide(fakeArgocdLayer(fake.fetch))),
+    );
+    expect(fake.seen.every((call) => call.method !== 'DELETE')).toBe(true);
+  });
+
+  test('the DELETE call itself returning 404 (a race with an external removal) still succeeds', async () => {
+    // ⚠️ fetchLive's pre-check finds the cluster live, but something else deregisters it before
+    //   this call's own DELETE lands — matching upstream's Hetzner/Certificate.ts `deleteById`.
+    const fake = fakeArgocd((method) =>
+      method === 'GET' ? liveCluster() : fakeFailure(404, 'cluster not found'),
+    );
+    await Effect.runPromise(
+      argocdOperations(spec)
+        .destroy({ server: SERVER })
+        .pipe(Effect.provide(fakeArgocdLayer(fake.fetch))),
+    );
+    expect(fake.seen.filter((call) => call.method === 'DELETE')).toHaveLength(1);
+  });
+});
+
+describe('Argocd.Cluster spec.upsert — write-only bearer token', () => {
+  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: { bearerToken: { fromEnv: ENV_VAR } }, server: SERVER })
+          .pipe(Effect.provide(fakeArgocdLayer(fake.fetch))),
+      ),
+    );
+    expect(failure._tag).toBe('ArgocdClusterSecretEnvUnsetError');
+    expect(fake.seen).toEqual([]);
+  });
+
+  test('resolves the bearer token into config, never the FromEnv reference itself', async () => {
+    process.env[ENV_VAR] = 'kube-bearer-abc123';
+    const fake = fakeArgocd((method) =>
+      method === 'POST' ? Response.json({ server: SERVER }) : fakeFailure(404, 'x'),
+    );
+    await Effect.runPromise(
+      spec
+        .upsert({
+          credentials: { bearerToken: { fromEnv: ENV_VAR } },
+          namespaces: ['argocd', 'apps'],
+          server: SERVER,
+        })
+        .pipe(Effect.provide(fakeArgocdLayer(fake.fetch))),
+    );
+    const [create] = fake.seen.filter((call) => call.method === 'POST');
+    expect(create?.path).toContain('upsert=true');
+    const body = create?.body as { config?: { bearerToken?: string }; namespaces?: string[] };
+    expect(body.config?.bearerToken).toBe('kube-bearer-abc123');
+    expect(body.namespaces).toEqual(['argocd', 'apps']);
+    expect(JSON.stringify(body)).not.toContain('fromEnv');
+  });
+});

package/src/argocd/cluster.ts

@@ -0,0 +1,222 @@
+/**
+ * `Argocd.Cluster` — a target Kubernetes cluster registered with an Argo CD instance
+ * (`/api/v1/clusters`) so Applications can deploy onto it. REST-managed, not a CRD; see
+ * `docs/argocd.md`. This is how the house will register the Talos-on-PVE cluster itself with
+ * Argo CD once both exist — Argo CD's own control-plane cluster (where Argo CD is installed) is
+ * registered implicitly as `https://kubernetes.default.svc` and never needs this resource.
+ *
+ * ⚠️ ONLY BEARER-TOKEN AND STATIC TLS CLIENT-CERT AUTH ARE SUPPORTED. `V1alpha1ClusterConfig` also
+ *   carries `awsAuthConfig` (EKS IAM) and `execProviderConfig` (an exec plugin) — measured in
+ *   `services/argocd.ts`, distilled homeflare/base — neither of which applies to a Talos cluster;
+ *   left unbuilt rather than modeled and untested.
+ *
+ * ⚠️ NO LIVE ARGO CD INSTANCE EXISTS ON THE ESTATE (2026-09-24) — see `docs/argocd.md`.
+ *
+ * ⛔ `defaultRemovalPolicy: 'retain'` — deregistering a cluster Applications still target breaks
+ *   their sync. `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 Data from 'effect/Data';
+import * as Effect from 'effect/Effect';
+import { type FromEnv, resolveAll } from '../secrets/write-only.ts';
+import { type ArgocdRequirements, type ArgocdSpec, argocdHandlers, present } from './resource.ts';
+
+export interface ClusterCredentialRefs {
+  readonly password?: FromEnv;
+  readonly bearerToken?: FromEnv;
+  readonly tlsClientKeyData?: FromEnv;
+}
+
+export interface ClusterProps {
+  /** The cluster's API server URL — identity key; changing it is a replace. */
+  server: string;
+  name?: string;
+  /** Restricts this cluster to one Argo CD project; omit for every project. */
+  project?: string;
+  namespaces?: readonly string[];
+  clusterResources?: boolean;
+  labels?: Readonly<Record<string, string>>;
+  annotations?: Readonly<Record<string, string>>;
+  proxyUrl?: string;
+  username?: string;
+  tlsCaData?: string;
+  /** The client certificate itself — public, unlike its key. */
+  tlsCertData?: string;
+  tlsInsecure?: boolean;
+  tlsServerName?: string;
+  /** Write-only — never a value here, only env var names. See the module header. */
+  credentials?: ClusterCredentialRefs;
+}
+
+export interface ClusterAttributes {
+  server: string;
+  name: string | undefined;
+  project: string | undefined;
+  namespaces: readonly string[] | undefined;
+  clusterResources: boolean | undefined;
+  labels: Readonly<Record<string, string>> | undefined;
+  annotations: Readonly<Record<string, string>> | undefined;
+  proxyUrl: string | undefined;
+  username: string | undefined;
+  tlsCaData: string | undefined;
+  tlsCertData: string | undefined;
+  tlsInsecure: boolean | undefined;
+  tlsServerName: string | undefined;
+}
+
+export interface ArgocdCluster extends Resource<
+  'Argocd.Cluster',
+  ClusterProps,
+  ClusterAttributes,
+  never,
+  ArgocdRequirements
+> {}
+
+export const ArgocdCluster = Resource<ArgocdCluster>('Argocd.Cluster', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/** Domain refusal, not a distilled error — a declared credential's env var is unset at call time. */
+export class ArgocdClusterSecretEnvUnsetError extends Data.TaggedError(
+  'ArgocdClusterSecretEnvUnsetError',
+)<{
+  readonly message: string;
+}> {}
+
+interface ResolvedClusterCredentials {
+  readonly password?: string;
+  readonly bearerToken?: string;
+  readonly tlsClientKeyData?: string;
+}
+
+const resolveClusterCredentials = (
+  refs: ClusterCredentialRefs,
+): Effect.Effect<ResolvedClusterCredentials, ArgocdClusterSecretEnvUnsetError> => {
+  const declared: Record<string, FromEnv> = {};
+  if (refs.password !== undefined) declared.password = refs.password;
+  if (refs.bearerToken !== undefined) declared.bearerToken = refs.bearerToken;
+  if (refs.tlsClientKeyData !== undefined) declared.tlsClientKeyData = refs.tlsClientKeyData;
+  const { values, missing } = resolveAll(declared);
+  if (missing.length > 0) {
+    return Effect.fail(
+      new ArgocdClusterSecretEnvUnsetError({
+        message:
+          `credential write requires ${missing.join(', ')}, unset or empty in the ` +
+          'deploying environment. Export it and deploy again.',
+      }),
+    );
+  }
+  return Effect.succeed(values as ResolvedClusterCredentials);
+};
+
+/**
+ * `V1alpha1Cluster.labels`/`.annotations` decode as `{ [key: string]: string | undefined }` — a
+ * generated index-signature artifact, not a real possibility on the wire (a label/annotation map
+ * never carries an `undefined` value). Cast at this one boundary rather than threading the looser
+ * type through `ClusterAttributes`.
+ */
+const attributesOf = (live: argocd.V1alpha1Cluster): ClusterAttributes => ({
+  annotations: live.annotations as Record<string, string> | undefined,
+  clusterResources: live.clusterResources,
+  labels: live.labels as Record<string, string> | undefined,
+  name: live.name,
+  namespaces: live.namespaces,
+  project: live.project,
+  proxyUrl: live.config?.proxyUrl,
+  server: live.server ?? '',
+  tlsCaData: live.config?.tlsClientConfig?.caData,
+  tlsCertData: live.config?.tlsClientConfig?.certData,
+  tlsInsecure: live.config?.tlsClientConfig?.insecure,
+  tlsServerName: live.config?.tlsClientConfig?.serverName,
+  username: live.config?.username,
+});
+
+const sameRecord = (
+  a: Readonly<Record<string, string>> | undefined,
+  b: Readonly<Record<string, string>> | undefined,
+) =>
+  JSON.stringify(Object.entries(a ?? {}).sort()) === JSON.stringify(Object.entries(b ?? {}).sort());
+
+const sameList = (a: readonly string[] | undefined, b: readonly string[] | undefined) =>
+  JSON.stringify([...(a ?? [])].sort()) === JSON.stringify([...(b ?? [])].sort());
+
+/** Only the plain fields — Argo CD never returns the password/bearer token/private key back. */
+const plainMatches = (attrs: ClusterAttributes, props: ClusterProps): boolean =>
+  (props.name ?? undefined) === (attrs.name ?? undefined) &&
+  (props.project ?? undefined) === (attrs.project ?? undefined) &&
+  sameList(props.namespaces, attrs.namespaces) &&
+  Boolean(props.clusterResources) === Boolean(attrs.clusterResources) &&
+  sameRecord(props.labels, attrs.labels) &&
+  sameRecord(props.annotations, attrs.annotations) &&
+  (props.proxyUrl ?? undefined) === (attrs.proxyUrl ?? undefined) &&
+  (props.username ?? undefined) === (attrs.username ?? undefined) &&
+  (props.tlsCaData ?? undefined) === (attrs.tlsCaData ?? undefined) &&
+  (props.tlsCertData ?? undefined) === (attrs.tlsCertData ?? undefined) &&
+  Boolean(props.tlsInsecure) === Boolean(attrs.tlsInsecure) &&
+  (props.tlsServerName ?? undefined) === (attrs.tlsServerName ?? undefined);
+
+type ClusterError =
+  | argocd.GetClusterServiceError
+  | argocd.CreateClusterServiceError
+  | argocd.DeleteClusterServiceError
+  | ArgocdClusterSecretEnvUnsetError;
+
+/** ★ EXPORTED for direct testing against `fake-argocd.ts` — see `cluster.test.ts`. */
+export const spec: ArgocdSpec<
+  ClusterProps,
+  argocd.V1alpha1Cluster,
+  ClusterAttributes,
+  ClusterError
+> = {
+  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
+      .deleteClusterService({ id_value: props.server })
+      .pipe(Effect.catchTag('NotFound', () => Effect.void)),
+  identityOfAttributes: (attrs) => attrs.server,
+  identityOfProps: (props) => props.server,
+  fetchLive: (props) =>
+    argocd
+      .getClusterService({ id_value: props.server })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+  matches: plainMatches,
+  upsert: (props) =>
+    resolveClusterCredentials(props.credentials ?? {}).pipe(
+      Effect.flatMap((creds) =>
+        argocd.createClusterService(
+          present({
+            upsert: true,
+            annotations: props.annotations,
+            clusterResources: props.clusterResources,
+            config: present({
+              bearerToken: creds.bearerToken,
+              password: creds.password,
+              proxyUrl: props.proxyUrl,
+              tlsClientConfig: present({
+                caData: props.tlsCaData,
+                certData: props.tlsCertData,
+                insecure: props.tlsInsecure,
+                keyData: creds.tlsClientKeyData,
+                serverName: props.tlsServerName,
+              }),
+              username: props.username,
+            }),
+            labels: props.labels,
+            name: props.name,
+            namespaces: props.namespaces === undefined ? undefined : [...props.namespaces],
+            project: props.project,
+            server: props.server,
+          }),
+        ),
+      ),
+    ),
+};
+
+export const handlers = argocdHandlers(spec);
+
+export const ArgocdClusterProvider = () =>
+  Provider.effect(ArgocdCluster, Effect.succeed(ArgocdCluster.Provider.of(handlers)));

package/src/argocd/credentials.ts

@@ -0,0 +1,38 @@
+/**
+ * Argo CD credentials — a bearer-token REFERENCE, resolved lazily, 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/argocd/Credentials` already ships exactly the shape this asks
+ *   for: `Credentials` is a lazy `Context.Service<Credentials, Effect.Effect<Config>>`, resolved
+ *   on the calling fiber inside each operation (`ArgocdProtocol`'s `credentials:` field), never at
+ *   layer build. This file re-exports it rather than re-implementing it — the same choice
+ *   `../discord/credentials.ts` and `../forgejo` (via `@distilled.cloud/forgejo/Credentials`) made.
+ *
+ * ★ `CredentialsFromEnv` reads `ARGOCD_TOKEN` (required) and `ARGOCD_SERVER` (optional instance
+ *   origin, default `https://localhost:8080`) — the distilled package's own names, unchanged here
+ *   so a consumer never has to guess which var this family reads.
+ *
+ * ⚠️ NO `credentials(...)` FACTORY EXISTS ON THIS SDK, unlike Discord/Grafana's — measured against
+ *   `packages/argocd/src/credentials.ts` (distilled homeflare/base): only `fromToken({ token,
+ *   apiBaseUrl? })` and `CredentialsFromEnv`. `fake-argocd.ts` builds its test layer from
+ *   `fromToken` directly.
+ *
+ * ⚠️ NO OpenBao MINT YET, same as every other family in this kit today (`Alchemy.Stack({ secrets
+ *   })` is unreleased, PR 1728, `main`-only). A deploy process exports `ARGOCD_TOKEN` itself —
+ *   this package never reads it from a file.
+ *
+ * ⚠️ NO LIVE ARGO CD INSTANCE EXISTS ON THE ESTATE YET (2026-09-24) — this family is built ahead
+ *   of the Talos-on-PVE cluster it targets, per Tim's "get the providers ready even if we don't
+ *   use it yet but we know we will." Nothing here has been exercised against a real server; every
+ *   test in this family runs against `fake-argocd.ts`.
+ */
+import type { Config } from '@distilled.cloud/argocd/Credentials';
+import { Credentials, CredentialsFromEnv, fromToken } from '@distilled.cloud/argocd/Credentials';
+
+/** Re-exported so a consumer never has to reach into `@distilled.cloud/argocd` by hand. */
+export { Credentials, CredentialsFromEnv, fromToken };
+export type { Config as ArgocdCredentialsConfig };
+
+/** `ArgocdCredentials.fromEnv()` — the layer every `argocdProviders()` stack uses by default. */
+export const fromEnv = () => CredentialsFromEnv;

package/src/argocd/fake-argocd.ts

@@ -0,0 +1,60 @@
+/**
+ * A minimal in-memory Argo CD REST API for this family's tests — an in-memory `fetch` handed to
+ * Effect's real `FetchHttpClient` through its `Fetch` reference, mirroring `../discord/fake-discord.ts`
+ * (itself mirroring `../forgejo/fake-forgejo.ts` and `cloudflare/fake-mesh.ts`). Tests exercise
+ * distilled's REAL path assembly, JSON encode/decode and status→typed-error matching — nothing
+ * about any of that is re-implemented here, only the wire responses a scenario needs.
+ *
+ * ⛔ TEST-ONLY, AND NO NETWORK. No provider imports this file. The base URL is RFC 2606
+ *   `argocd.example.com`, and the token is a placeholder. NO LIVE ARGO CD INSTANCE EXISTS ON THE
+ *   ESTATE (2026-09-24) — this is the only server any test in this family talks to.
+ */
+import { type Credentials, fromToken } from '@distilled.cloud/argocd/Credentials';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+
+export const FAKE_BASE = 'https://argocd.example.com';
+export const FAKE_TOKEN = 'placeholder-argocd-token';
+
+export type Seen = { readonly method: string; readonly path: string; readonly body: unknown };
+
+/** Argo CD's grpc-gateway `{ code?, message, error? }` failure envelope. */
+export const fakeFailure = (status: number, message: string, code?: number) =>
+  Response.json({ code, error: message, message }, { status });
+
+/**
+ * `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 fakeArgocd = (
+  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 — `ArgocdOpContext`, what every
+ * resource file's exported `spec.fetchLive`/`spec.upsert`/`spec.destroy` needs.
+ *
+ * ⚠️ NOT PAIRED WITH `handlers` (each resource file's `argocdHandlers(spec)` export). `handlers`
+ *   bakes in `CredentialsFromEnv`, which resolves through Effect's `Config` snapshot of
+ *   `process.env` — untestable against a fake server without mutating the real environment. So a
+ *   test calls `spec.fetchLive`/`spec.upsert`/`spec.destroy` directly, with this explicit layer,
+ *   exercising exactly the same production code without that env seam.
+ */
+export const fakeArgocdLayer = (
+  fetchFn: typeof globalThis.fetch,
+  creds: Layer.Layer<Credentials> = fromToken({ apiBaseUrl: FAKE_BASE, token: FAKE_TOKEN }),
+) => Layer.mergeAll(creds, FetchHttpClient.layer, Layer.succeed(FetchHttpClient.Fetch, fetchFn));

package/src/argocd/git-credentials.ts

@@ -0,0 +1,71 @@
+/**
+ * The write-only credential shape `Repository` and `RepoCreds` share — Argo CD's own REST schema
+ * gives both the same four secret-shaped fields (`password`, `sshPrivateKey`, `bearerToken`,
+ * `tlsClientCertKey` — measured against `V1alpha1Repository`/`V1alpha1RepoCreds` in the generated
+ * `services/argocd.ts`, distilled homeflare/base). One helper here instead of two copies.
+ *
+ * ⛔ NO SECRET VALUE IS EVER A PROP OR AN ATTRIBUTE — `../secrets/write-only.ts`'s rule. A prop
+ *   carries only the NAME of the environment variable holding a value (`FromEnv`); the value is
+ *   read at call time and sent on the wire, never stored.
+ *
+ * ⚠️ NO DRIFT DETECTION ON THE SECRET FIELDS, ON PURPOSE — same simplification
+ *   `../forgejo/org-actions-secrets.ts` makes for the identical problem (Argo CD's GET never
+ *   returns `password`/`sshPrivateKey`/`bearerToken`/`tlsClientCertKey` back, so there is nothing
+ *   to diff against). `matches` in each resource file compares only the PLAIN fields the API does
+ *   return; a changed credential is written once on create and never rotated automatically —
+ *   rotate by destroy-then-create, or a manual call outside Alchemy. A seal-based drift check
+ *   (`../secrets/write-only.ts#seal`) is possible later if that limitation becomes a real problem;
+ *   `proxmox/pbs-notification-target-lifecycle.ts` is the reference for what that costs in file size.
+ */
+import * as Data from 'effect/Data';
+import * as Effect from 'effect/Effect';
+import { type FromEnv, resolveAll } from '../secrets/write-only.ts';
+
+export interface GitCredentialRefs {
+  readonly password?: FromEnv;
+  readonly sshPrivateKey?: FromEnv;
+  readonly bearerToken?: FromEnv;
+  readonly tlsClientCertKey?: FromEnv;
+}
+
+export interface ResolvedGitCredentials {
+  readonly password?: string;
+  readonly sshPrivateKey?: string;
+  readonly bearerToken?: string;
+  readonly tlsClientCertKey?: string;
+}
+
+/** Domain refusal, not a distilled error — a declared credential's env var is unset at call time. */
+export class ArgocdSecretEnvUnsetError extends Data.TaggedError('ArgocdSecretEnvUnsetError')<{
+  readonly message: string;
+}> {}
+
+/** Only the refs actually declared — `resolveAll` takes no `undefined` values. */
+const declaredRefs = (refs: GitCredentialRefs): Readonly<Record<string, FromEnv>> => {
+  const out: Record<string, FromEnv> = {};
+  if (refs.password !== undefined) out.password = refs.password;
+  if (refs.sshPrivateKey !== undefined) out.sshPrivateKey = refs.sshPrivateKey;
+  if (refs.bearerToken !== undefined) out.bearerToken = refs.bearerToken;
+  if (refs.tlsClientCertKey !== undefined) out.tlsClientCertKey = refs.tlsClientCertKey;
+  return out;
+};
+
+/**
+ * Resolves every declared ref from the deploying process's own environment, or fails with the
+ * names of whichever are missing — never a value, in the failure or anywhere else.
+ */
+export const resolveGitCredentials = (
+  refs: GitCredentialRefs,
+): Effect.Effect<ResolvedGitCredentials, ArgocdSecretEnvUnsetError> => {
+  const { values, missing } = resolveAll(declaredRefs(refs));
+  if (missing.length > 0) {
+    return Effect.fail(
+      new ArgocdSecretEnvUnsetError({
+        message:
+          `credential write requires ${missing.join(', ')}, unset or empty in the ` +
+          'deploying environment. Export it and deploy again.',
+      }),
+    );
+  }
+  return Effect.succeed(values as ResolvedGitCredentials);
+};

package/src/argocd/index.ts

@@ -0,0 +1,40 @@
+/**
+ * Argo CD providers for Alchemy.
+ *
+ * ⛔ THIS BARREL IS THE PUBLIC API, AND IT IS DELIBERATELY SMALLER THAN THE DIRECTORY. `resource.ts`
+ *   and `git-credentials.ts` are internals the three resource files share — a consumer builds
+ *   against the resources and `providers()`, not the engine underneath.
+ *
+ * ★ `Application` AND `AppProject` ARE NOT HERE — they are Kubernetes CRDs, not Argo CD REST-only
+ *   objects, and the upstream-correct owner is Alchemy's own `Kubernetes.Manifest`
+ *   (`alchemy/Kubernetes`, v2.0.0-beta.79). See `docs/argocd.md#applications-and-appprojects` for
+ *   the measured reasoning and worked examples — no code for those two lives in this kit.
+ */
+export {
+  ArgocdCluster,
+  ArgocdClusterProvider,
+  type ClusterAttributes,
+  type ClusterCredentialRefs,
+  type ClusterProps,
+} from './cluster.ts';
+export {
+  type ArgocdCredentialsConfig,
+  Credentials,
+  CredentialsFromEnv,
+  fromEnv,
+  fromToken,
+} from './credentials.ts';
+export { type ArgocdSecretEnvUnsetError, type GitCredentialRefs } from './git-credentials.ts';
+export { providers } from './providers.ts';
+export {
+  ArgocdRepoCreds,
+  ArgocdRepoCredsProvider,
+  type RepoCredsAttributes,
+  type RepoCredsProps,
+} from './repo-creds.ts';
+export {
+  ArgocdRepository,
+  ArgocdRepositoryProvider,
+  type RepositoryAttributes,
+  type RepositoryProps,
+} from './repository.ts';

package/src/argocd/providers.ts

@@ -0,0 +1,17 @@
+/**
+ * All three Argo CD providers as one layer for a stack.
+ *
+ *     Layer.mergeAll(argocdProviders(), …the stack's other providers)
+ *       .pipe(Layer.provide(FetchHttpClient.layer))
+ *
+ * Mirrors `../discord/providers.ts`: `FetchHttpClient.layer` is the stack's own responsibility to
+ * provide (the shared transport every family needs), not something a single vendor's `providers()`
+ * should pin.
+ */
+import * as Layer from 'effect/Layer';
+import { ArgocdClusterProvider } from './cluster.ts';
+import { ArgocdRepoCredsProvider } from './repo-creds.ts';
+import { ArgocdRepositoryProvider } from './repository.ts';
+
+export const providers = () =>
+  Layer.mergeAll(ArgocdRepositoryProvider(), ArgocdRepoCredsProvider(), ArgocdClusterProvider());